# umap-js

> JavaScript implementation of UMAP

Latest version **1.4.0** (published 2024-06-05) · MIT license · 0 weekly downloads

## Install

```sh
npm install umap-js
pnpm add umap-js
yarn add umap-js
bun add umap-js
```

## Health

**Score 35/100 (D)** — status: abandoned.

Positive: has types; no vulnerabilities; high quality score.

Warnings: low downloads; no esm support.

Negative: abandoned.

## Facts

| | |
|---|---|
| Version | 1.4.0 |
| Published | 2024-06-05 |
| First published | 2019-02-21 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | CommonJS |
| Dependencies | 1 |
| Unpacked size | 498.1 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 433 |
| Author | Andy Coenen |
| Maintainers | google-wombot |

## Links

- npm: https://www.npmjs.com/package/umap-js
- Repository: https://github.com/PAIR-code/umap-js
- Homepage: https://github.com/PAIR-code/umap-js#readme
- Issues: https://github.com/PAIR-code/umap-js/issues
- npm.io page: https://npm.io/package/umap-js

## Dependencies (1)

- [ml-levenberg-marquardt](https://npm.io/package/ml-levenberg-marquardt.md) ^2.0.0

## Recent versions

- 1.4.0 (latest) — 2024-06-05
- 1.3.3 — 2020-10-14
- 1.3.2 — 2020-01-22
- 1.3.1 — 2019-06-08
- 1.3.0 — 2019-06-05
- 1.2.2 — 2019-05-23
- 1.2.1 — 2019-05-23
- 1.2.0 — 2019-05-23
- 1.1.2 — 2019-05-23
- 1.1.1 — 2019-05-03
- 1.1.0 — 2019-05-02
- 1.0.6 — 2019-04-25
- 1.0.5 — 2019-04-10
- 1.0.4 — 2019-04-10
- 1.0.3 — 2019-02-22
- … 3 more at https://npm.io/package/umap-js/versions

## README

[![Build Status](https://travis-ci.com/PAIR-code/umap-js.svg?branch=master)](https://travis-ci.com/PAIR-code/umap-js.svg?branch=master)

# UMAP-JS

This is a JavaScript reimplementation of UMAP from the python implementation found at https://github.com/lmcinnes/umap.

Uniform Manifold Approximation and Projection (UMAP) is a dimension reduction technique that can be used for visualisation similarly to t-SNE, but also for general non-linear dimension reduction.

There are a few important differences between the python implementation and the JS port.

- The optimization step is seeded with a random embedding rather than a spectral embedding. This gives comparable results for smaller datasets. The spectral embedding computation relies on efficient eigenvalue / eigenvector computations that are not easily done in JS.
- There is no specialized functionality for angular distances or sparse data representations.

### Usage

#### Installation

```sh
yarn add umap-js
```

#### Synchronous fitting

```javascript
import { UMAP } from 'umap-js';

const umap = new UMAP();
const embedding = umap.fit(data);
```

#### Asynchronous fitting

```javascript
import { UMAP } from 'umap-js';

const umap = new UMAP();
const embedding = await umap.fitAsync(data, epochNumber => {
  // check progress and give user feedback, or return `false` to stop
});
```

#### Step-by-step fitting

```javascript
import { UMAP } from 'umap-js';

const umap = new UMAP();
const nEpochs = umap.initializeFit(data);
for (let i = 0; i < nEpochs; i++) {
  umap.step();
}
const embedding = umap.getEmbedding();
```

#### Supervised projection using labels

```javascript
import { UMAP } from 'umap-js';

const umap = new UMAP();
umap.setSupervisedProjection(labels);
const embedding = umap.fit(data);
```

#### Transforming additional points after fitting

```javascript
import { UMAP } from 'umap-js';

const umap = new UMAP();
umap.fit(data);
const transformed = umap.transform(additionalData);
```

#### Parameters

The UMAP constructor can accept a number of hyperparameters via a `UMAPParameters` object, with the most common described below. See [umap.ts](./src/umap.ts) for more details.

| Parameter     | Description                                                                                                                         | default                                                                                                             |
| ------------- | ----------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------- |
| `nComponents` | The number of components (dimensions) to project the data to                                                                        | 2                                                                                                                   |
| `nEpochs`     | The number of epochs to optimize embeddings via SGD                                                                                 | (computed automatically)                                                                                            |
| `nNeighbors`  | The number of nearest neighbors to construct the fuzzy manifold                                                                     | 15                                                                                                                  |
| `minDist`     | The effective minimum distance between embedded points, used with `spread` to control the clumped/dispersed nature of the embedding | 0.1                                                                                                                 |
| `spread`      | The effective scale of embedded points, used with `minDist` to control the clumped/dispersed nature of the embedding                | 1.0                                                                                                                 |
| `random`      | A pseudo-random-number generator for controlling stochastic processes                                                               | `Math.random`                                                                                                       |
| `distanceFn`  | A custom distance function to use                                                                                                   | [`euclidean`](https://github.com/PAIR-code/umap-js/blob/73f181c8d7b58b051006aff7e492e259d6a32251/src/umap.ts#L1076) |

```typescript
const umap = new UMAP({
  nComponents: 2,
  nEpochs: 400,
  nNeighbors: 15,
});
```

### Testing

`umap-js` uses [`jest`](https://jestjs.io/) for testing.

```
yarn test
```

**This is not an officially supported Google product**

---
_Source: https://npm.io/package/umap-js · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._