@outsidedata/dolex 0.1.0

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

@@ -0,0 +1,126 @@
+/**
+ * Density Plot — smooth continuous distribution curve.
+ *
+ * Uses kernel density estimation (KDE) to show the probability density
+ * of continuous values. Like a smooth histogram without binning artifacts.
+ * Supports 2-4 overlapping group distributions for comparison.
+ */
+
+import type { VisualizationPattern, VisualizationSpec } from '../../../types.js';
+
+export const densityPlotPattern: VisualizationPattern = {
+  id: 'density-plot',
+  name: 'Density Plot',
+  category: 'distribution',
+  description:
+    'Smooth continuous curve showing probability density using kernel density estimation (KDE). Reveals distribution shape without binning artifacts.',
+  bestFor:
+    'Visualizing the shape of a continuous distribution. Comparing 2-4 overlapping distributions. Finding multimodal patterns, skewness, and tails.',
+  notFor:
+    'Small samples under 20 data points. Discrete or categorical data. More than 5 overlapping distributions (too much overplotting).',
+
+  dataRequirements: {
+    minRows: 20,
+    requiredColumns: [
+      { type: 'numeric', count: 1, description: 'Continuous value to estimate density for' },
+    ],
+    maxCategories: 5,
+  },
+
+  selectionRules: [
+    {
+      condition: 'Intent explicitly mentions density, KDE, or kernel density',
+      weight: 80,
+      matches: (ctx) => {
+        return /\b(density\s*plot|density\s*curve|kde|kernel\s*density|probability\s*density)\b/i.test(ctx.intent);
+      },
+    },
+    {
+      condition: 'Continuous numeric data with enough rows for smooth KDE estimation',
+      weight: 45,
+      matches: (ctx) => {
+        return (
+          ctx.dataShape.numericColumnCount >= 1 &&
+          ctx.dataShape.rowCount >= 20 &&
+          ctx.dataShape.categoricalColumnCount <= 1
+        );
+      },
+    },
+    {
+      condition: 'Intent mentions smooth distribution or distribution shape comparison',
+      weight: 55,
+      matches: (ctx) => {
+        return /\b(smooth\s*distribution|distribution\s*shape|distribution\s*comparison|overlapping\s*distribution|compare\s*distributions)\b/i.test(ctx.intent);
+      },
+    },
+    {
+      condition: 'Few groups (2-4) with continuous values — ideal for overlaid density curves',
+      weight: 35,
+      matches: (ctx) => {
+        return (
+          ctx.dataShape.numericColumnCount >= 1 &&
+          ctx.dataShape.categoricalColumnCount >= 1 &&
+          ctx.dataShape.categoryCount >= 2 &&
+          ctx.dataShape.categoryCount <= 4 &&
+          ctx.dataShape.rowCount >= 30
+        );
+      },
+    },
+    {
+      condition: 'Penalize for very small samples — KDE unreliable under 20 points',
+      weight: -40,
+      matches: (ctx) => {
+        return ctx.dataShape.rowCount < 20;
+      },
+    },
+    {
+      condition: 'Penalize for categorical-only data — density needs continuous values',
+      weight: -50,
+      matches: (ctx) => {
+        return ctx.dataShape.numericColumnCount === 0;
+      },
+    },
+    {
+      condition: 'Penalize for too many groups — overlapping curves become unreadable',
+      weight: -30,
+      matches: (ctx) => {
+        return ctx.dataShape.categoryCount > 5;
+      },
+    },
+  ],
+
+  generateSpec: (data, columns, options) => {
+    const valueCol = columns[0];
+    const groupCol = columns.length > 1 ? columns[1] : undefined;
+
+    const spec: VisualizationSpec = {
+      pattern: 'density-plot',
+      title: options?.title ?? (groupCol ? `${valueCol} distribution by ${groupCol}` : `${valueCol} density`),
+      data,
+      encoding: {
+        x: {
+          field: valueCol,
+          type: 'quantitative',
+          title: valueCol,
+        },
+        ...(groupCol
+          ? {
+              color: {
+                field: groupCol,
+                type: 'nominal',
+              },
+            }
+          : {}),
+      },
+      config: {
+        valueField: valueCol,
+        ...(groupCol ? { categoryField: groupCol } : {}),
+        bandwidth: options?.bandwidth ?? 'auto',
+        showRug: options?.showRug ?? false,
+        filled: options?.filled ?? true,
+      },
+    };
+
+    return spec;
+  },
+};

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

@@ -0,0 +1,125 @@
+/**
+ * Histogram — standard frequency distribution.
+ *
+ * The baseline distribution chart. Bins continuous values and shows
+ * frequency counts. Good for understanding shape, spread, and central
+ * tendency of a single numeric variable.
+ */
+
+import type { VisualizationPattern, VisualizationSpec } from '../../../types.js';
+
+export const histogramPattern: VisualizationPattern = {
+  id: 'histogram',
+  name: 'Histogram',
+  category: 'distribution',
+  description:
+    'Bins continuous data into intervals and shows frequency of each bin. Reveals distribution shape: normal, skewed, bimodal, uniform.',
+  bestFor:
+    'Understanding the shape of a single numeric variable: salary distribution, age distribution, response time distribution.',
+  notFor:
+    'Categorical data (use bar), very small datasets under 20 rows (use strip plot), comparing distributions across groups (use violin or ridgeline).',
+
+  dataRequirements: {
+    minRows: 20,
+    requiredColumns: [
+      { type: 'numeric', count: 1, description: 'Continuous variable to bin' },
+    ],
+  },
+
+  selectionRules: [
+    {
+      condition: 'Single numeric column with enough rows for meaningful bins',
+      weight: 50,
+      matches: (ctx) => {
+        return (
+          ctx.dataShape.numericColumnCount >= 1 &&
+          ctx.dataShape.rowCount >= 20 &&
+          ctx.dataShape.categoricalColumnCount === 0
+        );
+      },
+    },
+    {
+      condition: 'Intent mentions distribution, frequency, or histogram',
+      weight: 40,
+      matches: (ctx) => {
+        return /\b(distribut|frequenc|histogram|how\s+many|count\s+of|spread|shape)\b/i.test(ctx.intent);
+      },
+    },
+    {
+      condition: 'Large dataset benefits from binning',
+      weight: 20,
+      matches: (ctx) => {
+        return ctx.dataShape.rowCount >= 100 && ctx.dataShape.numericColumnCount >= 1;
+      },
+    },
+    {
+      condition: 'Penalize when categorical columns present — probably a comparison, not distribution',
+      weight: -15,
+      matches: (ctx) => {
+        return ctx.dataShape.categoricalColumnCount >= 1 && !/distribut/i.test(ctx.intent);
+      },
+    },
+    {
+      condition: 'Penalize for very small datasets — strip plot is better',
+      weight: -30,
+      matches: (ctx) => {
+        return ctx.dataShape.rowCount < 20;
+      },
+    },
+  ],
+
+  generateSpec: (data, columns, options) => {
+    const valueCol = columns[0];
+    const values = data.map((d) => Number(d[valueCol])).filter((v) => !isNaN(v));
+    const min = Math.min(...values);
+    const max = Math.max(...values);
+
+    // Sturges' formula for bin count
+    const binCount = options?.binCount ?? Math.ceil(Math.log2(values.length) + 1);
+    const binWidth = (max - min) / binCount;
+
+    // Build bin data
+    const bins: Record<string, any>[] = [];
+    for (let i = 0; i < binCount; i++) {
+      const binStart = min + i * binWidth;
+      const binEnd = binStart + binWidth;
+      const count = values.filter((v) =>
+        i === binCount - 1 ? v >= binStart && v <= binEnd : v >= binStart && v < binEnd
+      ).length;
+      bins.push({
+        binStart,
+        binEnd,
+        binMid: (binStart + binEnd) / 2,
+        binLabel: `${binStart.toFixed(1)}-${binEnd.toFixed(1)}`,
+        count,
+      });
+    }
+
+    const spec: VisualizationSpec = {
+      pattern: 'histogram',
+      title: options?.title ?? `Distribution of ${valueCol}`,
+      data: bins,
+      encoding: {
+        x: {
+          field: 'binMid',
+          type: 'quantitative',
+          title: valueCol,
+        },
+        y: {
+          field: 'count',
+          type: 'quantitative',
+          title: 'Frequency',
+        },
+      },
+      config: {
+        binCount,
+        showMean: options?.showMean ?? true,
+        showMedian: options?.showMedian ?? false,
+        mean: values.reduce((a, b) => a + b, 0) / values.length,
+        median: values.sort((a, b) => a - b)[Math.floor(values.length / 2)],
+      },
+    };
+
+    return spec;
+  },
+};

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

@@ -0,0 +1,9 @@
+/**
+ * Distribution patterns — for understanding data spread, shape, and outliers.
+ */
+
+export { histogramPattern } from './histogram.js';
+export { beeswarmPattern } from './beeswarm.js';
+export { violinPattern } from './violin.js';
+export { ridgelinePattern } from './ridgeline.js';
+export { stripPlotPattern } from './strip-plot.js';

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

@@ -0,0 +1,120 @@
+/**
+ * Ridgeline Plot — multiple overlapping distributions.
+ *
+ * Also called a "joy plot". Stacks density curves vertically,
+ * allowing comparison of many distributions in a compact space.
+ * Works beautifully when you have 5-30 groups to compare.
+ */
+
+import type { VisualizationPattern, VisualizationSpec } from '../../../types.js';
+
+export const ridgelinePattern: VisualizationPattern = {
+  id: 'ridgeline',
+  name: 'Ridgeline Plot',
+  category: 'distribution',
+  description:
+    'Overlapping density curves stacked vertically. Compact way to compare many distributions simultaneously, revealing patterns across groups.',
+  bestFor:
+    'Comparing distributions across many groups (5-30): temperature by month, ratings by genre, scores by department.',
+  notFor:
+    'Few groups under 4 (use violin), single variable (use histogram), very small sample sizes per group.',
+
+  dataRequirements: {
+    minRows: 50,
+    requiredColumns: [
+      { type: 'numeric', count: 1, description: 'Value to show distribution of' },
+      { type: 'categorical', count: 1, description: 'Group variable (5-30 groups ideal)' },
+    ],
+    minCategories: 4,
+    maxCategories: 30,
+  },
+
+  selectionRules: [
+    {
+      condition: 'Many groups to compare (5-30) — ridgeline excels over violin',
+      weight: 75,
+      matches: (ctx) => {
+        return (
+          ctx.dataShape.numericColumnCount >= 1 &&
+          ctx.dataShape.categoricalColumnCount >= 1 &&
+          ctx.dataShape.categoryCount >= 5 &&
+          ctx.dataShape.categoryCount <= 30 &&
+          ctx.dataShape.rowCount >= 50
+        );
+      },
+    },
+    {
+      condition: 'Intent mentions multiple distributions or many groups',
+      weight: 50,
+      matches: (ctx) => {
+        return /\b(ridgeline|joy\s*plot|all\s+(distribut|groups)|each\s+(month|year|group|category)|across\s+all|by\s+month|by\s+year)\b/i.test(
+          ctx.intent
+        );
+      },
+    },
+    {
+      condition: 'Monthly or time-based grouping with enough data',
+      weight: 40,
+      matches: (ctx) => {
+        return (
+          ctx.dataShape.categoryCount >= 5 &&
+          ctx.dataShape.categoryCount <= 12 &&
+          /\b(month|season|quarter|year)\b/i.test(ctx.intent)
+        );
+      },
+    },
+    {
+      condition: 'Penalize for too few groups — use violin instead',
+      weight: -40,
+      matches: (ctx) => {
+        return ctx.dataShape.categoryCount < 4;
+      },
+    },
+    {
+      condition: 'Penalize for insufficient data per group',
+      weight: -30,
+      matches: (ctx) => {
+        if (ctx.dataShape.categoryCount === 0) return false;
+        const avgPerGroup = ctx.dataShape.rowCount / ctx.dataShape.categoryCount;
+        return avgPerGroup < 10;
+      },
+    },
+  ],
+
+  generateSpec: (data, columns, options) => {
+    const valueCol = columns[0];
+    const groupCol = columns.length > 1 ? columns[1] : columns[0];
+
+    const spec: VisualizationSpec = {
+      pattern: 'ridgeline',
+      title: options?.title ?? `${valueCol} distribution by ${groupCol}`,
+      data,
+      encoding: {
+        x: {
+          field: valueCol,
+          type: 'quantitative',
+          title: valueCol,
+        },
+        y: {
+          field: groupCol,
+          type: 'nominal',
+          title: groupCol,
+        },
+        color: {
+          field: groupCol,
+          type: 'nominal',
+        },
+      },
+      config: {
+        valueField: valueCol,
+        categoryField: groupCol,
+        overlap: options?.overlap ?? 0.6,
+        bandwidth: options?.bandwidth ?? 'auto',
+        fillOpacity: options?.fillOpacity ?? 0.7,
+        strokeWidth: options?.strokeWidth ?? 1.5,
+      },
+    };
+
+    return spec;
+  },
+};

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

@@ -0,0 +1,106 @@
+/**
+ * Strip Plot — small dataset distribution.
+ *
+ * The simplest distribution plot: just dots along an axis.
+ * No binning, no density estimation. For small datasets where
+ * every point can be individually seen and each value matters.
+ */
+
+import type { VisualizationPattern, VisualizationSpec } from '../../../types.js';
+
+export const stripPlotPattern: VisualizationPattern = {
+  id: 'strip-plot',
+  name: 'Strip Plot',
+  category: 'distribution',
+  description:
+    'Individual data points plotted along a single axis with minimal jitter. The simplest distribution view for small datasets where every point matters.',
+  bestFor:
+    'Small datasets (5-50 rows), comparing distributions across groups when sample size is too small for density estimation.',
+  notFor:
+    'Large datasets over 100 (points overlap — use histogram or beeswarm), complex distribution analysis (use violin).',
+
+  dataRequirements: {
+    minRows: 3,
+    maxRows: 100,
+    requiredColumns: [
+      { type: 'numeric', count: 1, description: 'Value to plot' },
+    ],
+  },
+
+  selectionRules: [
+    {
+      condition: 'Very small dataset — strip plot shows every point clearly',
+      weight: 70,
+      matches: (ctx) => {
+        return (
+          ctx.dataShape.rowCount >= 3 &&
+          ctx.dataShape.rowCount <= 50 &&
+          ctx.dataShape.numericColumnCount >= 1
+        );
+      },
+    },
+    {
+      condition: 'Distribution intent with small data — too few points for histogram/violin',
+      weight: 60,
+      matches: (ctx) => {
+        return (
+          /\b(distribut|spread|point|individual)\b/i.test(ctx.intent) &&
+          ctx.dataShape.rowCount < 30
+        );
+      },
+    },
+    {
+      condition: 'Small sample per group — density estimation would be unreliable',
+      weight: 50,
+      matches: (ctx) => {
+        if (ctx.dataShape.categoryCount === 0) return false;
+        const avgPerGroup = ctx.dataShape.rowCount / ctx.dataShape.categoryCount;
+        return avgPerGroup < 15 && avgPerGroup >= 3;
+      },
+    },
+    {
+      condition: 'Penalize for large datasets — too many overlapping points',
+      weight: -50,
+      matches: (ctx) => {
+        return ctx.dataShape.rowCount > 100;
+      },
+    },
+  ],
+
+  generateSpec: (data, columns, options) => {
+    const valueCol = columns[0];
+    const groupCol = columns.length > 1 ? columns[1] : undefined;
+
+    const spec: VisualizationSpec = {
+      pattern: 'strip-plot',
+      title: options?.title ?? `${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',
+            }
+          : undefined,
+      },
+      config: {
+        dotRadius: options?.dotRadius ?? 5,
+        opacity: options?.opacity ?? 0.8,
+      },
+    };
+
+    return spec;
+  },
+};

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

@@ -0,0 +1,118 @@
+/**
+ * Violin Plot — distribution shape comparison.
+ *
+ * Combines a box plot with a kernel density estimate, showing
+ * the full shape of each distribution. Superior to box plots
+ * because bimodal and multimodal distributions are clearly visible.
+ */
+
+import type { VisualizationPattern, VisualizationSpec } from '../../../types.js';
+
+export const violinPattern: VisualizationPattern = {
+  id: 'violin',
+  name: 'Violin Plot',
+  category: 'distribution',
+  description:
+    'Mirrored density curves for each group, showing the full distribution shape. Reveals bimodality, skewness, and distribution differences that box plots hide.',
+  bestFor:
+    'Comparing distribution shapes across 2-8 groups. Finding bimodal distributions. Understanding where data is concentrated.',
+  notFor:
+    'Single group (use histogram), many groups over 10 (use ridgeline), small sample sizes under 30 per group (density estimate unreliable).',
+
+  dataRequirements: {
+    minRows: 30,
+    requiredColumns: [
+      { type: 'numeric', count: 1, description: 'Value to show distribution of' },
+      { type: 'categorical', count: 1, description: 'Group variable (2-8 groups)' },
+    ],
+    minCategories: 2,
+    maxCategories: 8,
+  },
+
+  selectionRules: [
+    {
+      condition: 'Comparing distributions across groups — violin shows shape',
+      weight: 65,
+      matches: (ctx) => {
+        return (
+          ctx.dataShape.numericColumnCount >= 1 &&
+          ctx.dataShape.categoricalColumnCount >= 1 &&
+          ctx.dataShape.categoryCount >= 2 &&
+          ctx.dataShape.categoryCount <= 8 &&
+          ctx.dataShape.rowCount >= 30
+        );
+      },
+    },
+    {
+      condition: 'Intent mentions distribution comparison or shape',
+      weight: 50,
+      matches: (ctx) => {
+        return /\b(distribut|shape|compar.+(distribut|spread)|violin|density|bimodal|multimodal)\b/i.test(
+          ctx.intent
+        );
+      },
+    },
+    {
+      condition: 'Enough data per group for reliable density estimation',
+      weight: 30,
+      matches: (ctx) => {
+        if (ctx.dataShape.categoryCount === 0) return false;
+        const avgPerGroup = ctx.dataShape.rowCount / ctx.dataShape.categoryCount;
+        return avgPerGroup >= 20;
+      },
+    },
+    {
+      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 — use ridgeline instead',
+      weight: -30,
+      matches: (ctx) => {
+        return ctx.dataShape.categoryCount > 8;
+      },
+    },
+  ],
+
+  generateSpec: (data, columns, options) => {
+    const valueCol = columns[0];
+    const groupCol = columns.length > 1 ? columns[1] : columns[0];
+
+    const spec: VisualizationSpec = {
+      pattern: 'violin',
+      title: options?.title ?? `Distribution of ${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,
+        sortBy: options?.sortBy ?? 'value',
+        sortOrder: options?.sortOrder ?? 'descending',
+        showBoxPlot: options?.showBoxPlot ?? true,
+        showMedian: options?.showMedian ?? true,
+        showQuartiles: options?.showQuartiles ?? true,
+        bandwidth: options?.bandwidth ?? 'auto',
+      },
+    };
+
+    return spec;
+  },
+};