{"id":16257,"library":"umap-js","title":"UMAP-JS Dimension Reduction","description":"UMAP-JS is a JavaScript implementation of the Uniform Manifold Approximation and Projection (UMAP) algorithm, a popular dimension reduction technique for both visualization and general non-linear dimension reduction. Currently stable at version 1.4.0, the library offers synchronous, asynchronous, and step-by-step fitting methods, allowing for flexible integration into various application contexts. Key differentiators from the original Python implementation include the use of a random embedding to seed the optimization step, rather than a spectral embedding, which yields comparable results for smaller datasets but avoids complex eigenvalue/eigenvector computations in JavaScript. The library also lacks specialized functionality for angular distances or sparse data representations. Releases appear to follow an irregular schedule, with the last publish about two years ago, but the project is maintained by PAIR-code, indicating ongoing support.","status":"active","version":"1.4.0","language":"javascript","source_language":"en","source_url":"https://github.com/PAIR-code/umap-js","tags":["javascript","typescript"],"install":[{"cmd":"npm install umap-js","lang":"bash","label":"npm"},{"cmd":"yarn add umap-js","lang":"bash","label":"yarn"},{"cmd":"pnpm add umap-js","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"The library primarily uses named exports. Direct CommonJS `require` for `UMAP` may not work as expected or might require destructuring.","wrong":"const UMAP = require('umap-js');","symbol":"UMAP","correct":"import { UMAP } from 'umap-js';"},{"note":"Type definition for constructor options when using TypeScript.","symbol":"UMAPParameters","correct":"import { UMAP, UMAPParameters } from 'umap-js';"},{"note":"Importing all exports into a namespace object.","wrong":"const umapjs = require('umap-js');","symbol":"* as umapjs","correct":"import * as umapjs from 'umap-js';"}],"quickstart":{"code":"import { UMAP } from 'umap-js';\n\n// Generate some sample high-dimensional data\nconst numSamples = 1000;\nconst numDimensions = 10;\nconst data: number[][] = [];\nfor (let i = 0; i < numSamples; i++) {\n  const sample: number[] = [];\n  for (let j = 0; j < numDimensions; j++) {\n    sample.push(Math.random() * 100);\n  }\n  data.push(sample);\n}\n\n// Initialize UMAP with custom parameters\nconst umap = new UMAP({\n  nComponents: 2,   // Reduce to 2 dimensions for visualization\n  nNeighbors: 10,   // Number of neighbors to consider\n  minDist: 0.05,    // Controls how tightly points are clustered together\n  spread: 1.0       // Controls the overall scale of the embedding\n});\n\nconsole.log('Starting UMAP fitting...');\n// Perform synchronous fitting\nconst embedding = umap.fit(data);\n\nconsole.log('UMAP fitting complete. First 5 embedded points:');\nconsole.log(embedding.slice(0, 5));\n\n// Example of transforming new data after fitting\nconst additionalData = [[1, 2, 3, 4, 5, 6, 7, 8, 9, 10], [10, 9, 8, 7, 6, 5, 4, 3, 2, 1]];\nconst transformedPoints = umap.transform(additionalData);\nconsole.log('Transformed additional points:');\nconsole.log(transformedPoints);","lang":"typescript","description":"Demonstrates initializing UMAP, generating sample data, performing synchronous dimension reduction, and transforming new data points."},"warnings":[{"fix":"Be aware of these architectural differences when porting Python UMAP workflows or expecting identical behavior. Evaluate performance on your specific datasets.","message":"UMAP-JS differs from the Python UMAP implementation in key ways. It uses a random embedding to seed the optimization step, rather than a spectral embedding, due to the complexity of efficient eigenvalue/eigenvector computations in JavaScript. This can lead to comparable results for smaller datasets but may behave differently or have performance implications for very large or complex datasets where spectral initialization is advantageous.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Preprocess sparse data into dense representations or calculate custom distance metrics if angular distances are critical for your application.","message":"The JavaScript port currently lacks specialized functionality for angular distances or sparse data representations, which are available in the Python UMAP library. Users requiring these features will need to implement them separately or preprocess their data accordingly.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Always use the officially documented named imports, primarily `UMAP`. Avoid importing internal symbols which are subject to change without major version bumps.","message":"While the 1.2.2 release fixed issues with the default import of `LM` (likely an internal component), reliance on undocumented or internal exports in older versions could have led to module resolution or runtime errors. It's best to stick to documented public APIs like `UMAP`.","severity":"gotcha","affected_versions":"<1.2.2"}],"env_vars":null,"last_verified":"2026-04-21T00:00:00.000Z","next_check":"2026-07-20T00:00:00.000Z","problems":[{"fix":"Ensure you are using named imports with ESM: `import { UMAP } from 'umap-js';` or proper destructuring for CJS: `const { UMAP } = require('umap-js');`.","cause":"Attempting to use `require('umap-js')` without destructuring for named exports, or using a default import syntax for a named export.","error":"TypeError: UMAP is not a constructor"},{"fix":"Install the package using your package manager: `npm install umap-js` or `yarn add umap-js`.","cause":"The `umap-js` package has not been installed or is not correctly listed in `package.json`.","error":"Module not found: Can't resolve 'umap-js'"}],"ecosystem":"npm"}