twokeys 2.2.0 → 3.0.1

package/README.md

@@ -1,422 +1,385 @@
-# Twokeys
-
-> A small data exploration and manipulation library, named after **John Tukey** — the legendary statistician who pioneered exploratory data analysis (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.
-
-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.
-
-## 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
-
-| Package | Description |
-|---------|-------------|
-| `twokeys` | Core TypeScript library |
-| `@buley/twokeys-wasm` | WebAssembly implementation with TypeScript fallback |
-| `@buley/twokeys-types` | Shared Zod schemas for runtime validation |
-
-## Installation
-
-```bash
-npm install twokeys
-# or
-bun add twokeys
-# or
-yarn add twokeys
-```
-
-For WASM acceleration (optional):
-
-```bash
-npm install @buley/twokeys-wasm
-```
-
-## Quick Start
-
-```typescript
-import { Series } 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]
-
-// Get a full description
-const desc = series.describe();
-console.log(desc.summary);
-```
-
-### Using WASM (Optional)
-
-```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
-
-```typescript
-import {
-  createGraphCatalog,
-  topologicalSort,
-  louvainCommunities,
-  kNearestNeighbors,
-  linkPrediction,
-  aStarShortestPath,
-  yenKShortestPaths,
-  allPairsShortestPaths,
-  maximumFlow,
-  minCostMaxFlow,
-} 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 } },
-]);
-```
-
-## Benchmarks
-
-Performance on different dataset sizes (operations per second, higher is better):
-
-### TypeScript Implementation
-
-| 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 |
-
-### 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": {...} }
-}
-```
-
-## API
-
-### Series
-
-The `Series` class provides methods for exploring 1-dimensional numerical data.
-
-```typescript
-import { Series } from 'twokeys';
-
-const series = new Series({ data: [1, 2, 3, 4, 5] });
-```
-
-#### 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 |
-
-#### Ranking & Counting
-
-| Method | Description |
-|--------|-------------|
-| `sorted()` | Sorted copy of data |
-| `ranked()` | Rank information with tie handling |
-| `counts()` | Frequency of each value |
-| `binned()` | Histogram-style bins |
-
-#### Transforms
-
-| Method | Description |
-|--------|-------------|
-| `logs()` | Natural logarithm of each value |
-| `roots()` | Square root of each value |
-| `inverse()` | Reciprocal (1/x) of each value |
-
-#### Smoothing
-
-| Method | Description |
-|--------|-------------|
-| `hanning()` | Hanning filter (running averages) |
-| `smooth()` | Tukey's 3RSSH smoothing |
-| `rough()` | Residuals (original - smooth) |
-
-#### Full Description
-
-```typescript
-series.describe();
-// Returns complete analysis including all of the above
-```
-
-### Points
-
-The `Points` class handles n-dimensional point data.
-
-```typescript
-import { Points } from 'twokeys';
-
-// 100 random 2D points
-const points = new Points({ count: 100, dimensionality: 2 });
-
-// Or provide your own data
-const myPoints = new Points({ data: [[1, 2], [3, 4], [5, 6]] });
-```
-
-### Twokeys
-
-The main class provides factory methods and utilities.
-
-```typescript
-import Twokeys from 'twokeys';
-
-// Generate random data
-const randomData = Twokeys.randomSeries(100, 50);  // 100 values, max 50
-const randomPoints = Twokeys.randomPoints(50, 3);  // 50 3D points
-
-// Access classes
-const series = new Twokeys.Series({ data: [1, 2, 3] });
-const points = new Twokeys.Points(100);
-```
-
-## Examples
-
-### Box Plot Data
-
-```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(),
-};
-```
-
-### Outlier Detection
-
-```typescript
-const series = new Series({ data: measurements });
-
-// Inner fences: 1.5 × IQR from hinges
-const suspicious = series.outliers();
-
-// Outer fences: 3 × IQR from hinges
-const extreme = series.outside();
-```
-
-### Letter Values Display
-
-```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 },
-//   ...
-// ]
-```
-
-### Stem-and-Leaf Display
-
-```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"
-// ]
-```
-
-### Data Transformation
-
-```typescript
-const series = new Series({ data: skewedData });
-
-// Try different transforms to normalize
-const logTransformed = series.logs();
-const sqrtTransformed = series.roots();
-```
-
-## 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
-```
-
-## License
-
-MIT
-
----
-
-*"The best thing about being a statistician is that you get to play in everyone's backyard."* — John Tukey
+# Twokeys
+
+> 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)
+
+## What Is This?
+
+Tukey taught us that **looking at data** is just as important as modeling it. Twokeys applies that philosophy to three domains:
+
+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
+
+Zero dependencies. Pure TypeScript. Works everywhere.
+
+## Installation
+
+```bash
+npm install twokeys
+# or
+bun add twokeys
+```
+
+## Graph EDA
+
+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 { graphEda, graphOutliers } from 'twokeys';
+
+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 },
+];
+
+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' }]
+```
+
+## Vector Distance & Similarity
+
+Standalone functions for vector math. These are the workhorses that `Points`, graph algorithms, and consumers all use.
+
+```typescript
+import {
+  cosineSimilarity,
+  euclideanDistance,
+  manhattanDistance,
+  mahalanobisDistance,
+  normalizeL2,
+  cosineSimilaritySparse,
+  jaccardSimilarity,
+  overlapCoefficient,
+} from 'twokeys';
+
+// 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
+```
+
+## Multivariate Analysis (Points)
+
+Full multivariate EDA: centroids, covariance, correlation, Mahalanobis outlier detection.
+
+```typescript
+import { Points } from 'twokeys';
+
+const points = new Points({
+  data: [
+    [1, 2, 3],
+    [4, 5, 6],
+    [7, 8, 9],
+    [100, 100, 100],  // outlier
+  ],
+});
+
+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
+```
+
+## 1D Exploratory Data Analysis (Series)
+
+The original Tukey toolkit: everything you need to explore univariate data.
+
+```typescript
+import { Series } from 'twokeys';
+
+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();
+```
+
+## Graph Algorithms
+
+Centrality, community detection, shortest paths, flow, clustering, and a GDS-style catalog.
+
+```typescript
+import {
+  // Centrality
+  degreeCentrality,
+  closenessCentrality,
+  betweennessCentrality,
+  pageRank,
+
+  // Community detection
+  louvainCommunities,
+  labelPropagationCommunities,
+
+  // Similarity & link prediction
+  nodeSimilarity,
+  kNearestNeighbors,
+  linkPrediction,
+
+  // Paths & flow
+  shortestPath,
+  aStarShortestPath,
+  yenKShortestPaths,
+  allPairsShortestPaths,
+  maximumFlow,
+  minCostMaxFlow,
+
+  // Structure
+  topologicalSort,
+  stronglyConnectedComponents,
+  weaklyConnectedComponents,
+  minimumSpanningTree,
+  articulationPointsAndBridges,
+  analyzeGraph,
+
+  // Clustering
+  kMeansClustering,
+  kMeansAuto,
+  hierarchicalClustering,
+  dbscan,
+
+  // TSP
+  travelingSalesmanApprox,
+
+  // GDS-style catalog
+  createGraphCatalog,
+} from 'twokeys';
+```
+
+### Clustering
+
+```typescript
+import { kMeansClustering, hierarchicalClustering, dbscan } from 'twokeys';
+
+const points = [
+  [1, 1], [1.5, 2], [3, 4],
+  [5, 7], [3.5, 5], [4.5, 5],
+  [3.5, 4.5],
+];
+
+// k-Means
+const km = kMeansClustering(points, 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
+
+// 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
+```
+
+### GDS-Style Catalog
+
+In-memory graph projections with procedure wrappers and pipelines, inspired by Neo4j GDS.
+
+```typescript
+import { createGraphCatalog } from 'twokeys';
+
+const gds = createGraphCatalog<string>();
+gds.project('social', nodes, edges, { directed: true });
+
+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 } },
+]);
+```
+
+## API Reference
+
+### Distance & Similarity (`distance.ts`)
+
+| 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 |
+
+### Graph EDA (`graph-eda.ts`)
+
+| 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 |
+
+### Series
+
+| 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()` |
+
+### Points
+
+| 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 |
+
+## Packages
+
+| Package | Description |
+|---------|-------------|
+| `twokeys` | Core TypeScript library |
+| `@buley/twokeys-wasm` | WebAssembly implementation with TypeScript fallback |
+| `@buley/twokeys-types` | Shared Zod schemas for runtime validation |
+
+## Benchmarks
+
+Performance on different dataset sizes (operations per second):
+
+| 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
+bun install
+bun test
+bun test --coverage
+bun run build
+```
+
+## 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
+
+---
+
+*"The best thing about being a statistician is that you get to play in everyone's backyard."* — John Tukey