@outsidedata/dolex 0.1.0

package/src/patterns/definitions/relationship/connected-scatter.ts

@@ -0,0 +1,123 @@
+/**
+ * Connected Scatterplot — two metrics over time.
+ *
+ * A scatter plot where points are connected chronologically,
+ * showing how the relationship between two variables evolves
+ * over time. The path tells a story that neither variable
+ * alone would reveal.
+ */
+
+import type { VisualizationPattern, VisualizationSpec } from '../../../types.js';
+
+export const connectedScatterPattern: VisualizationPattern = {
+  id: 'connected-scatter',
+  name: 'Connected Scatterplot',
+  category: 'relationship',
+  description:
+    'Scatter plot with points connected in time order. Shows how the relationship between two variables evolves: loops indicate cycles, spirals indicate drift.',
+  bestFor:
+    'Two metrics that change together over time: unemployment vs inflation (Phillips curve), GDP vs life expectancy, revenue vs customer count.',
+  notFor:
+    'Static two-variable relationship (use regular scatter), single variable over time (use line), many data points (path becomes tangled).',
+
+  dataRequirements: {
+    minRows: 5,
+    maxRows: 100,
+    requiredColumns: [
+      { type: 'date', count: 1, description: 'Time ordering' },
+      { type: 'numeric', count: 2, description: 'Two metrics to plot as x and y' },
+    ],
+    requiresTimeSeries: true,
+  },
+
+  selectionRules: [
+    {
+      condition: 'Two numeric variables + time dimension — connected scatter shows temporal evolution of relationship',
+      weight: 75,
+      matches: (ctx) => {
+        return (
+          ctx.dataShape.hasTimeSeries &&
+          ctx.dataShape.numericColumnCount >= 2 &&
+          ctx.dataShape.rowCount >= 5 &&
+          ctx.dataShape.rowCount <= 100
+        );
+      },
+    },
+    {
+      condition: 'Intent mentions two metrics over time or evolving relationship',
+      weight: 60,
+      matches: (ctx) => {
+        return /\b(two\s+(metric|variable|measure)|evolv|over\s+time.+(vs|versus|and)|phillips|relationship.+chang|how\s+.+\s+and\s+.+\s+chang)\b/i.test(
+          ctx.intent
+        );
+      },
+    },
+    {
+      condition: 'Penalize for too many data points — path becomes unreadable',
+      weight: -30,
+      matches: (ctx) => {
+        return ctx.dataShape.rowCount > 100;
+      },
+    },
+    {
+      condition: 'Penalize for no time dimension',
+      weight: -50,
+      matches: (ctx) => {
+        return !ctx.dataShape.hasTimeSeries;
+      },
+    },
+    {
+      condition: 'Penalize for single numeric variable',
+      weight: -40,
+      matches: (ctx) => {
+        return ctx.dataShape.numericColumnCount < 2;
+      },
+    },
+  ],
+
+  generateSpec: (data, columns, options) => {
+    const timeCol = columns[0];
+    const xMetricCol = columns.length > 1 ? columns[1] : columns[0];
+    const yMetricCol = columns.length > 2 ? columns[2] : columns.length > 1 ? columns[1] : columns[0];
+
+    // Sort by time
+    const sortedData = [...data].sort((a, b) => {
+      const aTime = new Date(a[timeCol]).getTime();
+      const bTime = new Date(b[timeCol]).getTime();
+      return aTime - bTime;
+    });
+
+    const spec: VisualizationSpec = {
+      pattern: 'connected-scatter',
+      title: options?.title ?? `${yMetricCol} vs ${xMetricCol} over ${timeCol}`,
+      data: sortedData,
+      encoding: {
+        x: {
+          field: xMetricCol,
+          type: 'quantitative',
+          title: xMetricCol,
+        },
+        y: {
+          field: yMetricCol,
+          type: 'quantitative',
+          title: yMetricCol,
+        },
+        order: {
+          field: timeCol,
+          type: 'temporal',
+        },
+      },
+      config: {
+        xField: xMetricCol,
+        yField: yMetricCol,
+        orderField: timeCol,
+        showLabels: options?.showLabels ?? true,
+        showArrows: options?.showArrows ?? true,
+        dotRadius: options?.dotRadius ?? 5,
+        strokeWidth: options?.strokeWidth ?? 2,
+      },
+    };
+
+    return spec;
+  },
+};

package/src/patterns/definitions/relationship/heatmap.ts

@@ -0,0 +1,168 @@
+/**
+ * Heatmap (Matrix) — color-encoded cells on two categorical axes.
+ *
+ * A grid where rows and columns represent categories, and cell color
+ * encodes a numeric value. Best for correlation matrices, cross-tabulation,
+ * frequency tables, and any dataset with two categorical + one numeric column.
+ */
+
+import type { VisualizationPattern, VisualizationSpec } from '../../../types.js';
+
+export const heatmapPattern: VisualizationPattern = {
+  id: 'heatmap',
+  name: 'Heatmap',
+  category: 'relationship',
+  description:
+    'A matrix grid where rows and columns are categories and cell color encodes a numeric value. Reveals patterns, clusters, and outliers in two-dimensional categorical data.',
+  bestFor:
+    'Correlation matrices, cross-tabulation, confusion matrices, frequency tables, skill matrices, attendance grids, any 2D categorical × numeric data.',
+  notFor:
+    'Time series (use calendar-heatmap or line), single categorical axis (use bar), continuous axes (use scatter), more than ~50 categories per axis (unreadable).',
+
+  dataRequirements: {
+    minRows: 2,
+    maxRows: 2500,
+    requiredColumns: [
+      { type: 'categorical', count: 2, description: 'Row and column categories' },
+      { type: 'numeric', count: 1, description: 'Value for cell color encoding' },
+    ],
+  },
+
+  selectionRules: [
+    {
+      condition: 'Intent mentions heatmap, matrix, correlation, cross-tab, or confusion matrix',
+      weight: 80,
+      matches: (ctx) => {
+        return /\b(heatmap|heat\s*map|matrix|correlation|cross[- ]?tab|confusion|crosstab|grid\s*chart)\b/i.test(
+          ctx.intent
+        );
+      },
+    },
+    {
+      condition: 'Two categorical columns + one numeric — classic heatmap shape',
+      weight: 55,
+      matches: (ctx) => {
+        return (
+          ctx.dataShape.categoricalColumnCount >= 2 &&
+          ctx.dataShape.numericColumnCount >= 1 &&
+          ctx.dataShape.rowCount >= 4
+        );
+      },
+    },
+    {
+      condition: 'Data looks like a matrix: row count ≈ product of two category cardinalities',
+      weight: 40,
+      matches: (ctx) => {
+        if (ctx.dataShape.categoricalColumnCount < 2) return false;
+        const cats = ctx.columns.filter(c => c.type === 'categorical');
+        if (cats.length < 2) return false;
+        const product = cats[0].uniqueCount * cats[1].uniqueCount;
+        const ratio = ctx.dataShape.rowCount / product;
+        return ratio >= 0.5 && ratio <= 1.5;
+      },
+    },
+    {
+      condition: 'Penalize if too many categories per axis (>50) — unreadable',
+      weight: -40,
+      matches: (ctx) => {
+        const cats = ctx.columns.filter(c => c.type === 'categorical');
+        return cats.some(c => c.uniqueCount > 50);
+      },
+    },
+    {
+      condition: 'Penalize if only one categorical column — bar chart is better',
+      weight: -30,
+      matches: (ctx) => {
+        return ctx.dataShape.categoricalColumnCount < 2;
+      },
+    },
+    {
+      condition: 'Penalize if data has time series characteristics — calendar-heatmap or line is better',
+      weight: -25,
+      matches: (ctx) => {
+        return ctx.dataShape.dateColumnCount > 0;
+      },
+    },
+  ],
+
+  generateSpec: (data, columns, options) => {
+    const catCols = columns.filter(c => {
+      const vals = data.map(d => d[c]);
+      const numeric = vals.every((v: any) => !isNaN(Number(v)) && v !== '' && v !== null);
+      return !numeric;
+    });
+    const numCols = columns.filter(c => !catCols.includes(c));
+
+    // Wide-format detection: 1 categorical + N>1 numeric → melt to long format
+    if (catCols.length === 1 && numCols.length > 1) {
+      const rowField = catCols[0];
+      const colFieldName = 'metric';
+      const valueFieldName = 'value';
+
+      const melted: Record<string, any>[] = [];
+      for (const row of data) {
+        for (const numCol of numCols) {
+          melted.push({
+            [rowField]: row[rowField],
+            [colFieldName]: numCol,
+            [valueFieldName]: Number(row[numCol]),
+          });
+        }
+      }
+
+      return {
+        pattern: 'heatmap',
+        title: options?.title ?? `${rowField} × Metrics`,
+        data: melted,
+        encoding: {
+          x: { field: colFieldName, type: 'nominal', title: 'Metric' },
+          y: { field: rowField, type: 'nominal', title: rowField },
+          color: {
+            field: valueFieldName,
+            type: 'quantitative',
+            title: 'Value',
+            palette: options?.palette,
+          },
+        },
+        config: {
+          rowField,
+          colField: colFieldName,
+          valueField: valueFieldName,
+          showValues: options?.showValues ?? true,
+          sortRows: options?.sortRows,
+          sortCols: options?.sortCols,
+        },
+      } satisfies VisualizationSpec;
+    }
+
+    const rowField = catCols[0] || columns[0];
+    const colField = catCols[1] || columns[1];
+    const valueField = numCols[0] || columns[2];
+
+    const spec: VisualizationSpec = {
+      pattern: 'heatmap',
+      title: options?.title ?? `${rowField} × ${colField}`,
+      data,
+      encoding: {
+        x: { field: colField, type: 'nominal', title: colField },
+        y: { field: rowField, type: 'nominal', title: rowField },
+        color: {
+          field: valueField,
+          type: 'quantitative',
+          title: valueField,
+          palette: options?.palette,
+        },
+      },
+      config: {
+        rowField,
+        colField,
+        valueField,
+        showValues: options?.showValues ?? true,
+        sortRows: options?.sortRows,
+        sortCols: options?.sortCols,
+      },
+    };
+
+    return spec;
+  },
+};

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

@@ -0,0 +1,8 @@
+/**
+ * Relationship patterns — for exploring correlations and multivariate data.
+ */
+
+export { scatterPattern } from './scatter.js';
+export { connectedScatterPattern } from './connected-scatter.js';
+export { parallelCoordinatesPattern } from './parallel-coordinates.js';
+export { radarPattern } from './radar.js';

package/src/patterns/definitions/relationship/parallel-coordinates.ts

@@ -0,0 +1,118 @@
+/**
+ * Parallel Coordinates — multivariate comparison.
+ *
+ * Each axis represents a variable. Each entity is a polyline
+ * connecting its values across all axes. Reveals which variables
+ * cluster together and how entities differ across many dimensions.
+ */
+
+import type { VisualizationPattern, VisualizationSpec } from '../../../types.js';
+
+export const parallelCoordinatesPattern: VisualizationPattern = {
+  id: 'parallel-coordinates',
+  name: 'Parallel Coordinates',
+  category: 'relationship',
+  description:
+    'Multiple parallel vertical axes, one per variable. Each entity is a polyline crossing all axes at its values. Reveals multivariate patterns, clusters, and tradeoffs.',
+  bestFor:
+    'Comparing entities across 4+ numeric dimensions: car specs (mpg, hp, weight, price), player stats, product features, survey multi-question analysis.',
+  notFor:
+    'Few variables under 3 (use scatter or bar), very many rows over 200 (lines overlap — filter first), non-numeric data.',
+
+  dataRequirements: {
+    minRows: 5,
+    maxRows: 200,
+    requiredColumns: [
+      { type: 'numeric', count: 3, description: 'Three or more numeric dimensions' },
+    ],
+  },
+
+  selectionRules: [
+    {
+      condition: 'Many numeric dimensions (4+) — parallel coordinates shows all at once',
+      weight: 80,
+      matches: (ctx) => {
+        return ctx.dataShape.numericColumnCount >= 4 && ctx.dataShape.rowCount <= 200;
+      },
+    },
+    {
+      condition: 'Intent mentions multivariate, dimensions, or profile comparison',
+      weight: 60,
+      matches: (ctx) => {
+        return /\b(multivariat|multi.dimension|across\s+all|all\s+(metrics|variables|dimensions)|profile|parallel|specs|specifications)\b/i.test(
+          ctx.intent
+        );
+      },
+    },
+    {
+      condition: 'Three numeric columns with categorical grouping — parallel coordinates with color',
+      weight: 50,
+      matches: (ctx) => {
+        return (
+          ctx.dataShape.numericColumnCount >= 3 &&
+          ctx.dataShape.categoricalColumnCount >= 1 &&
+          ctx.dataShape.categoryCount <= 8
+        );
+      },
+    },
+    {
+      condition: 'Penalize for few numeric columns — scatter or bar is simpler',
+      weight: -40,
+      matches: (ctx) => {
+        return ctx.dataShape.numericColumnCount < 3;
+      },
+    },
+    {
+      condition: 'Penalize for too many rows — lines become indistinguishable',
+      weight: -30,
+      matches: (ctx) => {
+        return ctx.dataShape.rowCount > 200;
+      },
+    },
+  ],
+
+  generateSpec: (data, columns, options) => {
+    // Separate numeric dimensions from categorical grouping column
+    const numericCols: string[] = [];
+    let groupCol: string | undefined = options?.groupField;
+
+    for (const col of columns) {
+      const sample = data.find(d => d[col] != null)?.[col];
+      if (typeof sample === 'number' || !isNaN(Number(sample))) {
+        numericCols.push(col);
+      } else if (!groupCol) {
+        groupCol = col;
+      }
+    }
+
+    const spec: VisualizationSpec = {
+      pattern: 'parallel-coordinates',
+      title: options?.title ?? `Multivariate comparison across ${numericCols.length} dimensions`,
+      data,
+      encoding: {
+        axes: numericCols.map((col) => ({
+          field: col,
+          type: 'quantitative' as const,
+          title: col,
+        })),
+        color: groupCol
+          ? {
+              field: groupCol,
+              type: 'nominal' as const,
+              title: groupCol,
+            }
+          : undefined,
+      },
+      config: {
+        dimensions: numericCols,
+        colorField: groupCol ?? null,
+        labelField: options?.labelField ?? numericCols[0],
+        showAxisLabels: options?.showAxisLabels ?? true,
+        lineOpacity: options?.lineOpacity ?? 0.4,
+        strokeWidth: options?.strokeWidth ?? 1.5,
+      },
+    };
+
+    return spec;
+  },
+};

package/src/patterns/definitions/relationship/radar.ts

@@ -0,0 +1,143 @@
+/**
+ * Radar Chart (Spider Chart) — multivariate profile.
+ *
+ * A radial chart where each axis extends from the center,
+ * one per variable. The resulting polygon shows the "shape"
+ * of an entity's profile. Best for comparing 1-3 entities
+ * across 5-10 dimensions.
+ */
+
+import type { VisualizationPattern, VisualizationSpec } from '../../../types.js';
+
+export const radarPattern: VisualizationPattern = {
+  id: 'radar',
+  name: 'Radar Chart',
+  category: 'relationship',
+  description:
+    'Radial axes extending from a center point, one per variable. Each entity forms a polygon. The shape reveals strengths, weaknesses, and overall profile.',
+  bestFor:
+    'Comparing 1-3 entity profiles across 5-10 dimensions: player stat comparison, product feature comparison, skill assessment, balanced scorecard.',
+  notFor:
+    'Many entities over 4 (polygons overlap), many dimensions over 12 (too dense), precise value comparison (radial distorts area).',
+
+  dataRequirements: {
+    minRows: 1,
+    maxRows: 12,
+    requiredColumns: [
+      { type: 'numeric', count: 3, description: 'Three or more metrics forming the profile' },
+    ],
+  },
+
+  selectionRules: [
+    {
+      condition: 'Few entities (1-3) with many metrics — radar shows the full profile shape',
+      weight: 75,
+      matches: (ctx) => {
+        return (
+          ctx.dataShape.numericColumnCount >= 4 &&
+          ctx.dataShape.numericColumnCount <= 12 &&
+          ctx.dataShape.rowCount >= 1 &&
+          ctx.dataShape.rowCount <= 4
+        );
+      },
+    },
+    {
+      condition: 'Intent mentions profile, strengths/weaknesses, or radar',
+      weight: 60,
+      matches: (ctx) => {
+        return /\b(profile|strength|weakness|radar|spider|skill|balanced|assessment|scorecard|attribute|stat|characteristic)\b/i.test(
+          ctx.intent
+        );
+      },
+    },
+    {
+      condition: 'Comparing exactly 2 entities across multiple metrics — radar overlay is powerful',
+      weight: 50,
+      matches: (ctx) => {
+        return (
+          ctx.dataShape.rowCount === 2 &&
+          ctx.dataShape.numericColumnCount >= 4
+        );
+      },
+    },
+    {
+      condition: 'Penalize for many entities — polygons become unreadable',
+      weight: -40,
+      matches: (ctx) => {
+        return ctx.dataShape.rowCount > 4;
+      },
+    },
+    {
+      condition: 'Penalize for few dimensions — scatter or bar is clearer',
+      weight: -30,
+      matches: (ctx) => {
+        return ctx.dataShape.numericColumnCount < 4;
+      },
+    },
+    {
+      condition: 'Penalize for many dimensions — too dense to read',
+      weight: -25,
+      matches: (ctx) => {
+        return ctx.dataShape.numericColumnCount > 12;
+      },
+    },
+  ],
+
+  generateSpec: (data, columns, options) => {
+    const entityCol = columns.find((_col, i) => {
+      // First column is often the entity label
+      return i === 0 && data.length > 1;
+    }) ?? columns[0];
+
+    // All other columns are metric dimensions
+    const metricCols = columns.filter((col) => col !== entityCol);
+
+    // Normalize values to 0-1 range for each metric
+    const normalizedData = data.map((row) => {
+      const normalized: Record<string, any> = { ...row };
+      for (const col of metricCols) {
+        const values = data.map((d) => Number(d[col]) || 0);
+        const min = Math.min(...values);
+        const max = Math.max(...values);
+        const range = max - min || 1;
+        normalized[`_norm_${col}`] = ((Number(row[col]) || 0) - min) / range;
+      }
+      return normalized;
+    });
+
+    const spec: VisualizationSpec = {
+      pattern: 'radar',
+      title: options?.title ?? `Profile comparison`,
+      data: normalizedData,
+      encoding: {
+        angle: {
+          field: '_dimension',
+          type: 'nominal',
+        },
+        radius: {
+          field: '_value',
+          type: 'quantitative',
+        },
+        color: data.length > 1
+          ? {
+              field: entityCol,
+              type: 'nominal',
+              title: entityCol,
+            }
+          : undefined,
+      },
+      config: {
+        categoryField: entityCol,
+        dimensions: metricCols,
+        showLabels: options?.showLabels ?? true,
+        showGrid: options?.showGrid ?? true,
+        gridLevels: options?.gridLevels ?? 5,
+        fillOpacity: options?.fillOpacity ?? 0.2,
+        strokeWidth: options?.strokeWidth ?? 2,
+        dotRadius: options?.dotRadius ?? 4,
+      },
+    };
+
+    return spec;
+  },
+};

package/src/patterns/definitions/relationship/scatter.ts

@@ -0,0 +1,138 @@
+/**
+ * Scatter Plot — two variables.
+ *
+ * The standard for showing the relationship between two numeric
+ * variables. Position encodes both values, revealing correlations,
+ * clusters, and outliers.
+ */
+
+import type { VisualizationPattern, VisualizationSpec } from '../../../types.js';
+
+export const scatterPattern: VisualizationPattern = {
+  id: 'scatter',
+  name: 'Scatter Plot',
+  category: 'relationship',
+  description:
+    'Each point represents one observation, positioned by two numeric variables. Reveals correlations, clusters, outliers, and the shape of relationships.',
+  bestFor:
+    'Exploring the relationship between two numeric variables: height vs weight, price vs quantity, score vs study hours.',
+  notFor:
+    'Categorical data (use bar), time series (use line unless comparing two metrics), single variable (use histogram).',
+
+  dataRequirements: {
+    minRows: 10,
+    requiredColumns: [
+      { type: 'numeric', count: 2, description: 'Two variables to compare' },
+    ],
+  },
+
+  selectionRules: [
+    {
+      condition: 'Two numeric columns — scatter is the natural choice for relationships',
+      weight: 60,
+      matches: (ctx) => {
+        return (
+          ctx.dataShape.numericColumnCount >= 2 &&
+          !ctx.dataShape.hasTimeSeries &&
+          ctx.dataShape.categoricalColumnCount <= 1
+        );
+      },
+    },
+    {
+      condition: 'Intent mentions correlation, relationship, or scatter',
+      weight: 50,
+      matches: (ctx) => {
+        return /\b(correlat|relationship|scatter|association|regress|predict|x\s+vs\s+y|versus)\b/i.test(
+          ctx.intent
+        );
+      },
+    },
+    {
+      condition: 'Enough data points for a meaningful scatter (10+)',
+      weight: 20,
+      matches: (ctx) => {
+        return ctx.dataShape.rowCount >= 10 && ctx.dataShape.numericColumnCount >= 2;
+      },
+    },
+    {
+      condition: 'Optional categorical column for color grouping',
+      weight: 15,
+      matches: (ctx) => {
+        return (
+          ctx.dataShape.numericColumnCount >= 2 &&
+          ctx.dataShape.categoricalColumnCount === 1 &&
+          ctx.dataShape.categoryCount <= 10
+        );
+      },
+    },
+    {
+      condition: 'Penalize for time series — use line or connected scatter',
+      weight: -30,
+      matches: (ctx) => {
+        return ctx.dataShape.hasTimeSeries;
+      },
+    },
+    {
+      condition: 'Penalize for single numeric column',
+      weight: -40,
+      matches: (ctx) => {
+        return ctx.dataShape.numericColumnCount < 2;
+      },
+    },
+  ],
+
+  generateSpec: (data, columns, options) => {
+    const xCol = columns[0];
+    const yCol = columns.length > 1 ? columns[1] : columns[0];
+    const colorCol = columns.length > 2 ? columns[2] : undefined;
+    const sizeCol = options?.sizeField
+      ? columns.find(c => c === options.sizeField)
+      : undefined;
+
+    const spec: VisualizationSpec = {
+      pattern: 'scatter',
+      title: options?.title ?? `${yCol} vs ${xCol}`,
+      data,
+      encoding: {
+        x: {
+          field: xCol,
+          type: 'quantitative',
+          title: xCol,
+        },
+        y: {
+          field: yCol,
+          type: 'quantitative',
+          title: yCol,
+        },
+        color: colorCol
+          ? {
+              field: colorCol,
+              type: 'nominal',
+              title: colorCol,
+            }
+          : undefined,
+        size: sizeCol
+          ? {
+              field: sizeCol,
+              type: 'quantitative' as const,
+              title: sizeCol,
+              range: options?.sizeRange ?? [3, 20] as [number, number],
+            }
+          : undefined,
+      },
+      config: {
+        xField: xCol,
+        yField: yCol,
+        colorField: colorCol ?? null,
+        sizeField: sizeCol ?? null,
+        dotRadius: options?.dotRadius ?? 5,
+        opacity: options?.opacity ?? 0.7,
+        showTrendLine: options?.showTrendLine ?? false,
+        showRegressionLine: options?.showRegressionLine ?? false,
+        jitter: options?.jitter ?? 0,
+      },
+    };
+
+    return spec;
+  },
+};