dimension-reduction

A high-quality TypeScript library for dimension reduction. Implements the core algorithm from the UMAP paper (Uniform Manifold Approximation and Projection) via the battle-tested umap-js port — the most faithful and performant JavaScript/TypeScript implementation available.

Designed with an ultra-simple, zero-ceremony API for embedding visualization.

Features

• 🔥 Ultra-simple API — Just convert_to_2d() or convert_to_3d()
• 📊 Perfect for RAG — Visualize high-dimensional embeddings from LLMs
• 🎯 Smart defaults — Auto-tuned parameters based on dataset size
• 🔒 Type-safe — Full TypeScript support with exported types
• ⚡ Fast — Powered by the optimized umap-js implementation
• 🧪 Well-tested — Comprehensive test suite
• 📦 Zero bloat — Single dependency, minimal footprint

Installation

npm install dimension-reduction
# or
yarn add dimension-reduction
# or
pnpm add dimension-reduction

Quick Start

import { convert_to_2d, convert_to_3d } from 'dimension-reduction';

// Your high-dimensional embeddings (e.g., from OpenAI, Claude, etc.)
const embeddings = [
  [0.1, 0.2, 0.3, ...],  // 768-dim or 1536-dim typical
  [0.4, 0.5, 0.6, ...],
  [0.7, 0.8, 0.9, ...],
  ...
];

// Reduce to 2D for scatter plots
const points2d = convert_to_2d(embeddings);
// [[x1, y1], [x2, y2], ...]

// Or reduce to 3D for interactive visualizations
const points3d = convert_to_3d(embeddings);
// [[x1, y1, z1], [x2, y2, z2], ...]

API Reference

convert_to_2d(embeddings, options?)

Reduce high-dimensional embeddings to 2D for scatter plots and 2D visualizations.

import { convert_to_2d, type Point2D } from 'dimension-reduction';

const points2d: Point2D[] = convert_to_2d(embeddings);
// Point2D = [number, number]

convert_to_3d(embeddings, options?)

Reduce high-dimensional embeddings to 3D for interactive 3D visualizations.

import { convert_to_3d, type Point3D } from 'dimension-reduction';

const points3d: Point3D[] = convert_to_3d(embeddings);
// Point3D = [number, number, number]

convert(embeddings, targetDim, options?)

Generic conversion to any target dimension (for advanced use cases).

import { convert } from 'dimension-reduction';

const reduced5d = convert(embeddings, 5);

Options

All functions accept an optional options object:

interface ReductionOptions {
  nNeighbors?: number; // Default: auto (5-15 based on dataset size)
  minDist?: number; // Default: 0.1
  spread?: number; // Default: 1.0
  learningRate?: number; // Default: 1.0
  negativeSampleRate?: number; // Default: 5
  nEpochs?: number; // Default: auto (200-500 based on dataset size)
  random?: () => number; // Custom random seed for reproducibility
}

Error Handling

The library throws ReductionError for:

• Empty embeddings arrays
• Mismatched vector dimensions
• Invalid numeric values (NaN, Infinity)
• Computation failures

import { convert_to_2d, ReductionError } from 'dimension-reduction';

try {
  const points = convert_to_2d(embeddings);
} catch (error) {
  if (error instanceof ReductionError) {
    console.error('Reduction failed:', error.message);
  }
}

Advanced Usage

Reproducible Results

For reproducible dimension reduction, provide a seeded random function:

// Simple LCG random number generator with seed
function createSeededRandom(seed: number) {
  return () => {
    seed = (seed * 9301 + 49297) % 233280;
    return seed / 233280;
  };
}

const points = convert_to_2d(embeddings, {
  random: createSeededRandom(42), // Same seed = same results
});

Custom Parameters

For fine-tuning the reduction:

const points = convert_to_2d(embeddings, {
  nNeighbors: 10, // Higher = more global structure
  minDist: 0.05, // Lower = tighter clusters
  spread: 0.8,
  learningRate: 0.5,
});

Raw UMAP Access

For full control, import the underlying UMAP class:

import { UMAP, type UMAPParameters } from 'dimension-reduction';

const umap = new UMAP({
  nComponents: 2,
  nNeighbors: 15,
  // ... any UMAP parameter
});

const result = umap.fit(embeddings);

Examples

RAG Document Visualization

import { convert_to_2d } from 'dimension-reduction';

// Embeddings from your vector database
const docEmbeddings = await fetchDocumentEmbeddings();

// Reduce to 2D for visualization
const points = convert_to_2d(docEmbeddings);

// Plot with your favorite charting library
for (let i = 0; i < points.length; i++) {
  const [x, y] = points[i];
  plotPoint(x, y, { label: docTitles[i], cluster: docClusters[i] });
}

Cluster Analysis

import { convert_to_3d } from 'dimension-reduction';

// Reduce to 3D for interactive exploration
const points3d = convert_to_3d(embeddings);

// points3d can be fed directly to Three.js, Plotly, or similar
render3DVisualization(points3d);

Requirements

• Node.js 18+
• TypeScript 5.0+ (for type definitions)

Browser Support

Works in all modern browsers. For bundling, ensure your build tool handles CommonJS dependencies (Vite, Webpack, Rollup, etc. all work out of the box).

License

MIT