twokeys 2.2.0 → 3.0.0

package/README.md

@@ -1,40 +1,22 @@
 # Twokeys
 
-> A small data exploration and manipulation library, named after **John Tukey** — the legendary statistician who pioneered exploratory data analysis (EDA).
+> Exploratory data analysis for graphs, vectors, and series — named after **John Tukey**, the legendary statistician who pioneered EDA.
 
 [![CI](https://github.com/buley/twokeys/actions/workflows/ci.yml/badge.svg)](https://github.com/buley/twokeys/actions/workflows/ci.yml)
 [![npm version](https://badge.fury.io/js/twokeys.svg)](https://www.npmjs.com/package/twokeys)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 
-## About John Tukey
-
-John Wilder Tukey (1915–2000) revolutionized how we look at data. He invented the box plot, coined the terms "bit" and "software," and championed the idea that **looking at data** is just as important as modeling it. His book *Exploratory Data Analysis* (1977) changed statistics forever.
+## What Is This?
 
-This library is named after him — a founding mind in [data exploration and analysis](http://en.wikipedia.org/wiki/Exploratory_data_analysis) and a personal hero of the author.
+Tukey taught us that **looking at data** is just as important as modeling it. Twokeys applies that philosophy to three domains:
 
-## Features
-
-- **Summary Statistics**: Mean, median, mode, trimean, quartiles (hinges)
-- **Outlier Detection**: Tukey fences (inner and outer)
-- **Letter Values**: Extended quartiles (eighths, sixteenths, etc.)
-- **Stem-and-Leaf**: Text-based distribution visualization
-- **Ranking**: Full ranking with tie handling
-- **Binning**: Histogram-style grouping
-- **Smoothing**: Hanning filter, Tukey's 3RSSH smoothing
-- **Transforms**: Logarithms, square roots, reciprocals
-- **Graph Analytics**: Centrality, communities, paths, flow, clustering, TSP approximation
-- **GDS-style Catalog**: In-memory graph projections with procedure wrappers and pipelines
-- **WASM Support**: Optional WebAssembly for maximum performance
-- **Zero Dependencies**: Pure TypeScript, works everywhere
-- **Tiny**: <3KB minified and gzipped
-
-## Packages
+1. **Graph EDA** — Treat structural properties of graphs (degree distributions, clustering coefficients, assortativity) as data series that deserve full Tukey-style analysis
+2. **Vector Distance & Similarity** — Cosine similarity, Mahalanobis distance, Jaccard similarity, L2 normalization, and more
+3. **Multivariate Analysis** — Centroids, covariance matrices, correlation matrices, and Mahalanobis-based outlier detection via the `Points` class
+4. **1D EDA** — The original `Series` class: medians, fences, letter values, stem-and-leaf plots, smoothing, and everything else Tukey invented
+5. **Graph Algorithms** — Centrality, community detection, shortest paths, flow, clustering (k-means, hierarchical, DBSCAN), TSP approximation, and a GDS-style catalog
 
-| Package | Description |
-|---------|-------------|
-| `twokeys` | Core TypeScript library |
-| `@buley/twokeys-wasm` | WebAssembly implementation with TypeScript fallback |
-| `@buley/twokeys-types` | Shared Zod schemas for runtime validation |
+Zero dependencies. Pure TypeScript. Works everywhere.
 
 ## Installation
 
@@ -42,377 +24,358 @@ This library is named after him — a founding mind in [data exploration and ana
 npm install twokeys
 # or
 bun add twokeys
-# or
-yarn add twokeys
 ```
 
-For WASM acceleration (optional):
+## Graph EDA
 
-```bash
-npm install @buley/twokeys-wasm
-```
-
-## Quick Start
+The core insight: graph structural properties ARE data series. Degree distributions get box plots. Clustering coefficients get outlier detection. Assortativity tells you whether your network is stratified.
 
 ```typescript
-import { Series } from 'twokeys';
+import { graphEda, graphOutliers } from 'twokeys';
 
-// Create a series from your data
-const series = new Series({ data: [1, 2, 3, 4, 5, 6, 7, 8, 9, 100] });
-
-// Get summary statistics
-console.log(series.mean());      // 14.5
-console.log(series.median());    // { datum: 5.5, depth: 5.5 }
-console.log(series.trimean());   // Tukey's trimean
-
-// Detect outliers (using Tukey fences)
-console.log(series.outliers());  // [100]
+const nodes = ['alice', 'bob', 'carol', 'dave', 'eve'] as const;
+const edges = [
+  { from: 'alice', to: 'bob', weight: 1 },
+  { from: 'alice', to: 'carol', weight: 1 },
+  { from: 'bob', to: 'carol', weight: 1 },
+  { from: 'carol', to: 'dave', weight: 1 },
+  { from: 'dave', to: 'eve', weight: 1 },
+];
 
-// Get a full description
-const desc = series.describe();
-console.log(desc.summary);
+const summary = graphEda(nodes, edges);
+
+// Every structural metric, analyzed as a Tukey Series:
+summary.density;                    // edges / maxPossibleEdges
+summary.degreeDistribution;         // Full SeriesDescription with median, fences, outliers
+summary.clusteringDistribution;     // Clustering coefficients as EDA
+summary.globalClusteringCoefficient;
+summary.averagePathLength;
+summary.diameter;
+summary.reciprocity;
+summary.degreeAssortativity;        // Do hubs connect to hubs?
+
+// Find structurally unusual nodes
+const unusual = graphOutliers(nodes, edges, { method: 'combined' });
+// [{ nodeId: 'eve', score: 2.1, reason: 'Low degree + low clustering' }]
 ```
 
-### Using WASM (Optional)
+## Vector Distance & Similarity
 
-```typescript
-import { loadWasm, analyze, isWasmLoaded } from '@buley/twokeys-wasm';
-
-// Load WASM (falls back to TypeScript if unavailable)
-await loadWasm();
-
-console.log(isWasmLoaded()); // true if WASM loaded
-
-// Use the same API - automatically uses WASM when available
-const result = analyze([1, 2, 3, 4, 5, 6, 7, 8, 9, 100]);
-console.log(result.summary.outliers); // [100]
-```
-
-## Graph Analytics + GDS-style Catalog
+Standalone functions for vector math. These are the workhorses that `Points`, graph algorithms, and consumers all use.
 
 ```typescript
 import {
-  createGraphCatalog,
-  topologicalSort,
-  louvainCommunities,
-  kNearestNeighbors,
-  linkPrediction,
-  aStarShortestPath,
-  yenKShortestPaths,
-  allPairsShortestPaths,
-  maximumFlow,
-  minCostMaxFlow,
+  cosineSimilarity,
+  euclideanDistance,
+  manhattanDistance,
+  mahalanobisDistance,
+  normalizeL2,
+  cosineSimilaritySparse,
+  jaccardSimilarity,
+  overlapCoefficient,
 } from 'twokeys';
 
-const nodes = ['root', 'plan', 'build', 'ship'] as const;
-const edges = [
-  { from: 'root', to: 'plan', weight: 1 },
-  { from: 'plan', to: 'build', weight: 2 },
-  { from: 'build', to: 'ship', weight: 1 },
-];
-
-// Vote-weighted linearization for "abstract -> concrete" flows
-const linear = topologicalSort(nodes, edges, {
-  priorityByNode: { ship: 10, build: 6, plan: 3 },
-});
-
-// Community + similarity/link prediction family
-const communities = louvainCommunities(nodes, edges);
-const knn = kNearestNeighbors(nodes, edges, { k: 2 });
-const links = linkPrediction(nodes, edges, { limit: 5 });
-
-// Path + flow family
-const aStar = aStarShortestPath(nodes, edges, 'root', 'ship');
-const yen = yenKShortestPaths(nodes, edges, 'root', 'ship', { k: 3 });
-const apsp = allPairsShortestPaths(nodes, edges);
-const maxFlow = maximumFlow(nodes, edges, 'root', 'ship');
-const minCost = minCostMaxFlow(
-  nodes,
-  edges.map((edge) => ({
-    from: edge.from,
-    to: edge.to,
-    capacity: edge.weight ?? 1,
-    cost: edge.weight ?? 1,
-  })),
-  'root',
-  'ship',
-);
-
-// GDS-style catalog/procedure wrapper
-const gds = createGraphCatalog<string>();
-gds.project('tasks', [...nodes], edges, { directed: true });
-const rank = gds.pageRank('tasks');
-const pipeline = gds.runPipeline('tasks', [
-  { id: 'rank', kind: 'page-rank' },
-  { id: 'sim', kind: 'similarity', options: { metric: 'jaccard' } },
-  { id: 'links', kind: 'link-prediction', options: { limit: 10 } },
-]);
+// Dense vectors
+cosineSimilarity([1, 2, 3], [4, 5, 6]);          // 0.974
+euclideanDistance([0, 0], [3, 4]);                  // 5
+manhattanDistance([0, 0], [3, 4]);                  // 7
+normalizeL2([3, 4]);                               // [0.6, 0.8]
+mahalanobisDistance([5, 5], [0, 0], [1, 1]);       // 7.07
+
+// Sparse vectors (Map<string, number>)
+const a = new Map([['x', 1], ['y', 2]]);
+const b = new Map([['y', 3], ['z', 4]]);
+cosineSimilaritySparse(a, b);                       // similarity on shared keys
+
+// Set similarity
+jaccardSimilarity(new Set([1, 2, 3]), new Set([2, 3, 4]));  // 0.5
+overlapCoefficient(new Set([1, 2]), new Set([2, 3, 4]));     // 0.5
 ```
 
-## Benchmarks
+## Multivariate Analysis (Points)
 
-Performance on different dataset sizes (operations per second, higher is better):
+Full multivariate EDA: centroids, covariance, correlation, Mahalanobis outlier detection.
 
-### TypeScript Implementation
+```typescript
+import { Points } from 'twokeys';
 
-| Method | 100 elements | 1,000 elements | 10,000 elements |
-|--------|-------------:|---------------:|----------------:|
-| `sorted()` | 224,599 | 14,121 | 874 |
-| `median()` | 199,397 | 14,127 | 876 |
-| `mean()` | 550,610 | 413,551 | 68,399 |
-| `mode()` | 87,665 | 6,738 | 431 |
-| `fences()` | 238,486 | 13,270 | 864 |
-| `outliers()` | 210,058 | 12,584 | 854 |
-| `smooth()` | 61,268 | 1,599 | 31 |
-| `describe()` | 15,642 | 952 | 29 |
+const points = new Points({
+  data: [
+    [1, 2, 3],
+    [4, 5, 6],
+    [7, 8, 9],
+    [100, 100, 100],  // outlier
+  ],
+});
 
-### v2.0 Performance Improvements
-
-Compared to v1.x (CoffeeScript), v2.0 TypeScript is dramatically faster:
-
-| Method | v1.x (10K) | v2.0 (10K) | Improvement |
-|--------|------------|------------|-------------|
-| `median()` | 6 ops/sec | 876 ops/sec | **146x faster** |
-| `counts()` | 1 ops/sec | 606 ops/sec | **606x faster** |
-| `fences()` | 5 ops/sec | 864 ops/sec | **173x faster** |
-| `describe()` | 1 ops/sec | 29 ops/sec | **29x faster** |
-
-Key optimizations:
-- O(1) index-based median (was O(n²) recursive)
-- Map-based frequency counting (was O(n²) recursive)
-- Eliminated unnecessary array copying in smoothing
-
-## Example Output
-
-Applying `describe()` to a Series returns a complete analysis:
-
-```javascript
-const series = new Series({ data: [48, 59, 63, 30, 57, 92, 73, 47, 31, 5] });
-const analysis = series.describe();
-
-// Result:
-{
-  "original": [48, 59, 63, 30, 57, 92, 73, 47, 31, 5],
-  "summary": {
-    "median": { "datum": 52.5, "depth": 5.5 },
-    "mean": 50.5,
-    "hinges": [{ "datum": 31, "depth": 3 }, { "datum": 63, "depth": 8 }],
-    "adjacent": [30, 92],
-    "outliers": [],
-    "extremes": [5, 92],
-    "iqr": 32,
-    "fences": [4.5, 100.5]
-  },
-  "smooths": {
-    "smooth": [48, 30, 57, 57, 57, 47, 31, 5, 5, 5],
-    "hanning": [48, 61, 46.5, 43.5, 74.5, 82.5, 60, 39, 18, 5]
-  },
-  "transforms": {
-    "logs": [3.87, 4.08, 4.14, ...],
-    "roots": [6.93, 7.68, 7.94, ...],
-    "inverse": [0.021, 0.017, 0.016, ...]
-  },
-  "sorted": [5, 30, 31, 47, 48, 57, 59, 63, 73, 92],
-  "ranked": { "up": {...}, "down": {...}, "groups": {...} },
-  "binned": { "bins": 4, "width": 26, "binned": {...} }
-}
+points.centroid();              // [28, 28.75, 29.5]
+points.variances();             // Per-dimension variance
+points.standardDeviations();    // Per-dimension stddev
+points.covarianceMatrix();      // Full covariance matrix
+points.correlationMatrix();     // Pearson correlation matrix
+
+// Mahalanobis distance — the multivariate equivalent of z-score
+points.mahalanobis([50, 50, 50]);   // Distance of a single point
+points.mahalanobisAll();             // Distance for each stored point
+
+// Tukey-style outlier detection for multivariate data
+points.outliersByMahalanobis();      // [[100, 100, 100]]
+
+// Normalization
+points.normalizeL2();     // L2-normalize all points (returns new Points)
+points.normalizeZscore(); // Z-score normalize per dimension
+
+// Full description — each dimension analyzed as a Series
+const desc = points.describe();
+desc.centroid;              // Mean point
+desc.correlationMatrix;     // Pearson correlations
+desc.mahalanobisDistances;  // Distance from centroid per point
+desc.outlierCount;          // How many outliers
+desc.dimensionSummaries;    // Each dimension as a full SeriesDescription
 ```
 
-## API
+## 1D Exploratory Data Analysis (Series)
 
-### Series
-
-The `Series` class provides methods for exploring 1-dimensional numerical data.
+The original Tukey toolkit: everything you need to explore univariate data.
 
 ```typescript
 import { Series } from 'twokeys';
 
-const series = new Series({ data: [1, 2, 3, 4, 5] });
+const series = new Series({ data: [2, 4, 4, 4, 5, 5, 7, 9] });
+
+// Summary statistics
+series.mean();       // 5
+series.median();     // { datum: 4.5, depth: 4.5 }
+series.mode();       // { count: 3, data: [4] }
+series.trimean();    // Tukey's trimean
+
+// Dispersion
+series.variance();   // Sample variance
+series.stddev();     // Standard deviation
+series.iqr();        // Interquartile range
+series.skewness();   // Fisher-Pearson skewness
+series.kurtosis();   // Excess kurtosis
+
+// Outlier detection (Tukey fences)
+series.fences();     // Inner fence boundaries (1.5 x IQR)
+series.outliers();   // Values outside inner fences
+series.outside();    // Values outside outer fences (3 x IQR)
+
+// Time series
+series.ema(0.3);     // Exponential moving average
+series.zscore();     // Z-score normalization
+series.hanning();    // Hanning filter
+series.smooth();     // Tukey's 3RSSH smoothing
+series.rough();      // Residuals (original - smooth)
+
+// Visualization
+series.stemLeaf();     // Stem-and-leaf plot
+series.letterValues();  // Extended quartiles (M, F, E, D, C, B, A...)
+
+// Everything at once
+series.describe();
 ```
 
-#### Summary Statistics
-
-| Method | Description |
-|--------|-------------|
-| `mean()` | Arithmetic mean |
-| `median()` | Median value and depth |
-| `mode()` | Most frequent value(s) |
-| `trimean()` | Tukey's trimean: (Q1 + 2×median + Q3) / 4 |
-| `extremes()` | [min, max] values |
-| `hinges()` | Quartile boundaries (Q1, Q3) |
-| `iqr()` | Interquartile range |
-
-#### Outlier Detection
-
-| Method | Description |
-|--------|-------------|
-| `fences()` | Inner fence boundaries (1.5 × IQR) |
-| `outer()` | Outer fence boundaries (3 × IQR) |
-| `outliers()` | Values outside inner fences |
-| `inside()` | Values within fences |
-| `outside()` | Values outside outer fences |
-| `adjacent()` | Most extreme non-outlier values |
-
-#### Letter Values & Visualization
-
-| Method | Description |
-|--------|-------------|
-| `letterValues()` | Extended quartiles (M, F, E, D, C, B, A...) |
-| `stemLeaf()` | Stem-and-leaf text display |
-| `midSummaries()` | Symmetric quantile pair averages |
+## Graph Algorithms
 
-#### Ranking & Counting
+Centrality, community detection, shortest paths, flow, clustering, and a GDS-style catalog.
 
-| Method | Description |
-|--------|-------------|
-| `sorted()` | Sorted copy of data |
-| `ranked()` | Rank information with tie handling |
-| `counts()` | Frequency of each value |
-| `binned()` | Histogram-style bins |
+```typescript
+import {
+  // Centrality
+  degreeCentrality,
+  closenessCentrality,
+  betweennessCentrality,
+  pageRank,
 
-#### Transforms
+  // Community detection
+  louvainCommunities,
+  labelPropagationCommunities,
 
-| Method | Description |
-|--------|-------------|
-| `logs()` | Natural logarithm of each value |
-| `roots()` | Square root of each value |
-| `inverse()` | Reciprocal (1/x) of each value |
+  // Similarity & link prediction
+  nodeSimilarity,
+  kNearestNeighbors,
+  linkPrediction,
 
-#### Smoothing
+  // Paths & flow
+  shortestPath,
+  aStarShortestPath,
+  yenKShortestPaths,
+  allPairsShortestPaths,
+  maximumFlow,
+  minCostMaxFlow,
 
-| Method | Description |
-|--------|-------------|
-| `hanning()` | Hanning filter (running averages) |
-| `smooth()` | Tukey's 3RSSH smoothing |
-| `rough()` | Residuals (original - smooth) |
+  // Structure
+  topologicalSort,
+  stronglyConnectedComponents,
+  weaklyConnectedComponents,
+  minimumSpanningTree,
+  articulationPointsAndBridges,
+  analyzeGraph,
+
+  // Clustering
+  kMeansClustering,
+  kMeansAuto,
+  hierarchicalClustering,
+  dbscan,
+
+  // TSP
+  travelingSalesmanApprox,
+
+  // GDS-style catalog
+  createGraphCatalog,
+} from 'twokeys';
+```
 
-#### Full Description
+### Clustering
 
 ```typescript
-series.describe();
-// Returns complete analysis including all of the above
-```
+import { kMeansClustering, hierarchicalClustering, dbscan } from 'twokeys';
 
-### Points
-
-The `Points` class handles n-dimensional point data.
+const points = [
+  [1, 1], [1.5, 2], [3, 4],
+  [5, 7], [3.5, 5], [4.5, 5],
+  [3.5, 4.5],
+];
 
-```typescript
-import { Points } from 'twokeys';
+// k-Means
+const km = kMeansClustering(points, 2);
 
-// 100 random 2D points
-const points = new Points({ count: 100, dimensionality: 2 });
+// Hierarchical (single, complete, average, or ward linkage)
+const hc = hierarchicalClustering(points, 2, { linkage: 'ward' });
+hc.clusters;     // Point indices per cluster
+hc.dendrogram;   // Merge history
+hc.silhouette;   // Cluster quality score
 
-// Or provide your own data
-const myPoints = new Points({ data: [[1, 2], [3, 4], [5, 6]] });
+// DBSCAN — density-based, finds natural shapes, handles noise
+const db = dbscan(points, 1.5, 2);
+db.clusters;      // Point indices per cluster
+db.noise;         // Indices of noise points
+db.clusterCount;  // Number of clusters found
 ```
 
-### Twokeys
+### GDS-Style Catalog
 
-The main class provides factory methods and utilities.
+In-memory graph projections with procedure wrappers and pipelines, inspired by Neo4j GDS.
 
 ```typescript
-import Twokeys from 'twokeys';
+import { createGraphCatalog } from 'twokeys';
 
-// Generate random data
-const randomData = Twokeys.randomSeries(100, 50);  // 100 values, max 50
-const randomPoints = Twokeys.randomPoints(50, 3);  // 50 3D points
+const gds = createGraphCatalog<string>();
+gds.project('social', nodes, edges, { directed: true });
 
-// Access classes
-const series = new Twokeys.Series({ data: [1, 2, 3] });
-const points = new Twokeys.Points(100);
+const rank = gds.pageRank('social');
+const pipeline = gds.runPipeline('social', [
+  { id: 'rank', kind: 'page-rank' },
+  { id: 'sim', kind: 'similarity', options: { metric: 'jaccard' } },
+  { id: 'links', kind: 'link-prediction', options: { limit: 10 } },
+]);
 ```
 
-## Examples
+## API Reference
 
-### Box Plot Data
+### Distance & Similarity (`distance.ts`)
 
-```typescript
-const series = new Series({ data: myData });
-
-const boxPlot = {
-  min: series.extremes()[0],
-  q1: series.hinges()[0].datum,
-  median: series.median().datum,
-  q3: series.hinges()[1].datum,
-  max: series.extremes()[1],
-  outliers: series.outliers(),
-};
-```
+| Function | Description |
+|----------|-------------|
+| `cosineSimilarity(a, b)` | Cosine similarity between dense vectors [-1, 1] |
+| `euclideanDistance(a, b)` | Euclidean (L2) distance |
+| `squaredEuclideanDistance(a, b)` | Squared Euclidean distance (avoids sqrt) |
+| `manhattanDistance(a, b)` | Manhattan (L1) distance |
+| `mahalanobisDistance(point, means, variances, epsilon?)` | Mahalanobis distance |
+| `normalizeL2(vector)` | L2-normalize a vector to unit length |
+| `cosineSimilaritySparse(a, b)` | Cosine similarity for sparse vectors (`Map<string, number>`) |
+| `jaccardSimilarity(a, b)` | Jaccard index for sets |
+| `overlapCoefficient(a, b)` | Overlap coefficient for sets |
 
-### Outlier Detection
+### Graph EDA (`graph-eda.ts`)
 
-```typescript
-const series = new Series({ data: measurements });
+| Function | Description |
+|----------|-------------|
+| `graphEda(nodes, edges, options?)` | Full Tukey-style EDA of graph structure |
+| `clusteringCoefficient(nodes, edges, options?)` | Per-node clustering coefficients |
+| `graphOutliers(nodes, edges, options?)` | Structurally unusual nodes |
 
-// Inner fences: 1.5 × IQR from hinges
-const suspicious = series.outliers();
+### Series
 
-// Outer fences: 3 × IQR from hinges
-const extreme = series.outside();
-```
+| Category | Methods |
+|----------|---------|
+| **Statistics** | `mean()`, `median()`, `mode()`, `trimean()`, `variance()`, `stddev()`, `skewness()`, `kurtosis()` |
+| **Dispersion** | `extremes()`, `hinges()`, `iqr()`, `fences()`, `outer()` |
+| **Outliers** | `outliers()`, `inside()`, `outside()`, `adjacent()` |
+| **Time Series** | `ema(alpha)`, `zscore()`, `hanning()`, `smooth()`, `rough()` |
+| **Visualization** | `stemLeaf()`, `letterValues()`, `midSummaries()` |
+| **Transforms** | `logs()`, `roots()`, `inverse()` |
+| **Sorting** | `sorted()`, `ranked()`, `counts()`, `binned()` |
 
-### Letter Values Display
+### Points
 
-```typescript
-const series = new Series({ data: myData });
-
-// Get extended quartiles
-const lv = series.letterValues();
-// [
-//   { letter: 'M', depth: 10.5, lower: 52.5, upper: 52.5, mid: 52.5, spread: 0 },
-//   { letter: 'F', depth: 5, lower: 31, upper: 73, mid: 52, spread: 42 },
-//   { letter: 'E', depth: 3, lower: 30, upper: 82, mid: 56, spread: 52 },
-//   ...
-// ]
-```
+| Method | Description |
+|--------|-------------|
+| `centroid()` | Mean point across all dimensions |
+| `variances()` | Per-dimension variance |
+| `standardDeviations()` | Per-dimension standard deviation |
+| `covarianceMatrix()` | Full covariance matrix |
+| `correlationMatrix()` | Pearson correlation matrix |
+| `mahalanobis(point)` | Mahalanobis distance of a single point from centroid |
+| `mahalanobisAll()` | Mahalanobis distance for each stored point |
+| `outliersByMahalanobis(threshold?)` | Points with Mahalanobis distance > threshold |
+| `normalizeL2()` | L2-normalize all points (returns new Points) |
+| `normalizeZscore()` | Z-score normalize per dimension (returns new Points) |
+| `describe()` | Full multivariate EDA summary |
+
+### Graph Algorithms
+
+| Category | Functions |
+|----------|-----------|
+| **Centrality** | `degreeCentrality`, `closenessCentrality`, `betweennessCentrality`, `pageRank` |
+| **Community** | `louvainCommunities`, `labelPropagationCommunities` |
+| **Similarity** | `nodeSimilarity`, `kNearestNeighbors`, `linkPrediction` |
+| **Paths** | `shortestPath`, `aStarShortestPath`, `yenKShortestPaths`, `allPairsShortestPaths` |
+| **Flow** | `maximumFlow`, `minCostMaxFlow` |
+| **Structure** | `topologicalSort`, `stronglyConnectedComponents`, `weaklyConnectedComponents`, `minimumSpanningTree`, `articulationPointsAndBridges`, `analyzeGraph` |
+| **Clustering** | `kMeansClustering`, `kMeansAuto`, `hierarchicalClustering`, `dbscan` |
+| **TSP** | `travelingSalesmanApprox` |
+| **Catalog** | `createGraphCatalog` — GDS-style projections and pipelines |
 
-### Stem-and-Leaf Display
+## Packages
 
-```typescript
-const series = new Series({ data: myData });
-
-const { display } = series.stemLeaf();
-// [
-//   "   0 | 5",
-//   "   3 | 0 1",
-//   "   4 | 7 8",
-//   "   5 | 7 9",
-//   "   6 | 3",
-//   "   7 | 3",
-//   "   9 | 2"
-// ]
-```
+| Package | Description |
+|---------|-------------|
+| `twokeys` | Core TypeScript library |
+| `@buley/twokeys-wasm` | WebAssembly implementation with TypeScript fallback |
+| `@buley/twokeys-types` | Shared Zod schemas for runtime validation |
 
-### Data Transformation
+## Benchmarks
 
-```typescript
-const series = new Series({ data: skewedData });
+Performance on different dataset sizes (operations per second):
 
-// Try different transforms to normalize
-const logTransformed = series.logs();
-const sqrtTransformed = series.roots();
-```
+| Method | 100 elements | 1,000 elements | 10,000 elements |
+|--------|-------------:|---------------:|----------------:|
+| `sorted()` | 224,599 | 14,121 | 874 |
+| `median()` | 199,397 | 14,127 | 876 |
+| `mean()` | 550,610 | 413,551 | 68,399 |
+| `mode()` | 87,665 | 6,738 | 431 |
+| `fences()` | 238,486 | 13,270 | 864 |
+| `outliers()` | 210,058 | 12,584 | 854 |
+| `smooth()` | 61,268 | 1,599 | 31 |
+| `describe()` | 15,642 | 952 | 29 |
 
 ## Development
 
 ```bash
-# Install dependencies
 bun install
-
-# Run tests
 bun test
-
-# Run tests with coverage
 bun test --coverage
-
-# Build all packages
 bun run build
-
-# Run benchmark
-bun run bench.ts
 ```
 
+## About John Tukey
+
+John Wilder Tukey (1915-2000) revolutionized how we look at data. He invented the box plot, coined the terms "bit" and "software," and championed the idea that looking at data is just as important as modeling it. His book *Exploratory Data Analysis* (1977) changed statistics forever.
+
+This library is named after him — a founding mind in [data exploration and analysis](http://en.wikipedia.org/wiki/Exploratory_data_analysis) and a personal hero of the author.
+
 ## License
 
 MIT