UMAP-JS Dimension Reduction

Common errors

• TypeError: UMAP is not a constructor

  cause Attempting to use `require('umap-js')` without destructuring for named exports, or using a default import syntax for a named export.
  fix Ensure you are using named imports with ESM: `import { UMAP } from 'umap-js';` or proper destructuring for CJS: `const { UMAP } = require('umap-js');`.

• Module not found: Can't resolve 'umap-js'

  cause The `umap-js` package has not been installed or is not correctly listed in `package.json`.
  fix Install the package using your package manager: `npm install umap-js` or `yarn add umap-js`.

Warnings

• gotcha 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.
  Fix: Be aware of these architectural differences when porting Python UMAP workflows or expecting identical behavior. Evaluate performance on your specific datasets.
• gotcha 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.
  Fix: Preprocess sparse data into dense representations or calculate custom distance metrics if angular distances are critical for your application.
• gotcha 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`.
  Fix: Always use the officially documented named imports, primarily `UMAP`. Avoid importing internal symbols which are subject to change without major version bumps.

Install

• npm install umap-js npm
• yarn add umap-js yarn
• pnpm add umap-js pnpm

Imports

• UMAP
  wrong:

  const UMAP = require('umap-js');

  correct:

  import { UMAP } from 'umap-js';

  The library primarily uses named exports. Direct CommonJS `require` for `UMAP` may not work as expected or might require destructuring.
• UMAPParameters

  import { UMAP, UMAPParameters } from 'umap-js';

  Type definition for constructor options when using TypeScript.
• * as umapjs
  wrong:

  const umapjs = require('umap-js');

  correct:

  import * as umapjs from 'umap-js';

  Importing all exports into a namespace object.

Quickstart

Demonstrates initializing UMAP, generating sample data, performing synchronous dimension reduction, and transforming new data points.

import { UMAP } from 'umap-js';

// Generate some sample high-dimensional data
const numSamples = 1000;
const numDimensions = 10;
const data: number[][] = [];
for (let i = 0; i < numSamples; i++) {
  const sample: number[] = [];
  for (let j = 0; j < numDimensions; j++) {
    sample.push(Math.random() * 100);
  }
  data.push(sample);
}

// Initialize UMAP with custom parameters
const umap = new UMAP({
  nComponents: 2,   // Reduce to 2 dimensions for visualization
  nNeighbors: 10,   // Number of neighbors to consider
  minDist: 0.05,    // Controls how tightly points are clustered together
  spread: 1.0       // Controls the overall scale of the embedding
});

console.log('Starting UMAP fitting...');
// Perform synchronous fitting
const embedding = umap.fit(data);

console.log('UMAP fitting complete. First 5 embedded points:');
console.log(embedding.slice(0, 5));

// Example of transforming new data after fitting
const additionalData = [[1, 2, 3, 4, 5, 6, 7, 8, 9, 10], [10, 9, 8, 7, 6, 5, 4, 3, 2, 1]];
const transformedPoints = umap.transform(additionalData);
console.log('Transformed additional points:');
console.log(transformedPoints);