@greenelab/hclust

中文文档
0.0.1发布于 2020/11/26MITESM + CJS零依赖近 30 天下载 5623

Agglomerative hierarchical clustering in JavaScript

原始使用文档
文档目录9 节
  1. hclust
  2. Usage
  3. clusterData({ data, key, distance, linkage, onProgress })
  4. euclideanDistance(arrayA, arrayB)
  5. avgDistance(arrayA, arrayB, distanceMatrix)
  6. Comparison with hcluster.js
  7. Making changes to the library
  8. Similar libraries
  9. Further reading

hclust

Agglomerative hierarchical clustering in JavaScript

Inspired by the MIT-licensed hcluster.js by @ChrisPolis. See the comparison of the two below.


Usage

Browser

<script src="hclust.min.js"></script>
<script>
  hclust.clusterData(...);
  hclust.euclideanDistance(...);
  hclust.avgDistance(...);
</script>

Node

npm install @greenelab/hclust

or

yarn add @greenelab/hclust

then

import { clusterData } from 'hclust';
import { euclideanDistance } from 'hclust';
import { avgDistance } from 'hclust';

clusterData({ data, key, distance, linkage, onProgress })

Parameters

data

The data you want to cluster, in the format:

[
  ...
  [ ... 1, 2, 3 ...],
  [ ... 1, 2, 3 ...],
  [ ... 1, 2, 3 ...],
  ...
]

or if key parameter is specified:

[
  ...
  { someKey: [ ... 1, 2, 3 ...] },
  { someKey: [ ... 1, 2, 3 ...] },
  { someKey: [ ... 1, 2, 3 ...] },
  ...
]

The entries in the outer array can be considered the rows and the entries within each row array can be considered the cols. Each row should have the same number of cols.

Default value: []

key

A string key to specify which values to extract from the data array. If omitted, data is assumed to be an array of arrays. If specified, data is assumed to be array of objects, each with a key that contains the values for that row.

Default value: ''

distance

A function to calculate the distance between two equal-dimension vectors, used in calculating the distance matrix, in the format:

function (arrayA, arrayB) { return someNumber; }

The function receives two equal-length arrays of numbers (ints or floats) and should return a number (int or float).

Default value: euclideanDistance from this hclust package

linkage

A function to calculate the distance between pairs of clusters based on a distance matrix, used in determining linkage criterion, in the format:

function (arrayA, arrayB, distanceMatrix) { return someNumber; }

The function receives two sets of indexes and the distance matrix computed between each datum and every other datum. The function should return a number (int or float)

Default value: averageDistance from this hclust package

onProgress

A function that is called several times throughout clustering, and is provided the current progress through the clustering, in the format:

function (progress) { }

The function receives the percent progress between 0 and 1.

Default value: an internal function that console.log's the progress

Note: postMessage is called in the same places as onProgress, if the script is running as a web worker.

Returns

const { clusters, distances, order, clustersGivenK } = clusterData(...);

clusters

The resulting cluster tree, in the format:

{
  indexes: [ ... Number, Number, Number ... ],
  height: Number,
  children: [ ... {}, {}, {} ... ]
}

distances

The computed distance matrix, in the format:

[
  ...
  [ ... Number, Number, Number ...],
  [ ... Number, Number, Number ...],
  [ ... Number, Number, Number ...]
  ...
]

order

The new order of the data, in terms of original data array indexes, in the format:

[ ... Number, Number, Number ... ]

Equivalent to clusters.indexes and clustersGivenK[1].

clustersGivenK

A list of tree slices in terms of original data array indexes, where index = K, in the format:

[
  [], // K = 0
  [ [] ], // K = 1
  [ [], [] ], // K = 2
  [ [], [], [] ], // K = 3
  [ [], [], [], [] ], // K = 4
  [ [], [], [], [], [] ] // K = 5
  ...
]

euclideanDistance(arrayA, arrayB)

Calculates the euclidean distance between two equal-dimension vectors.


avgDistance(arrayA, arrayB, distanceMatrix)

Calculates the average distance between pairs of clusters based on a distance matrix.


Comparison with hcluster.js

  • This package does not duplicate items from the original dataset in the results. Results are given in terms of indexes, either with respect to the original dataset or the distance matrix.
  • This package uses more modern JavaScript syntaxes and practices to make the code cleaner and simpler.
  • This package provides an onProgress callback and calls postMessage for use in web workers. Because clustering can take a long time with large data sets, you may want to run it as a web worker so the browser doesn't freeze for a long time, and you may need a callback so you can give users visual feedback on its progress.
  • This package makes some performance optimizations, such as removing unnecessary loops through big sets. It has been tested on various OS's (Windows, Mac, Linux, iOS, Android), devices (desktop, laptop, mobile), browsers (Chrome, Firefox, Safari), contexts (main thread, web worker), and hosting locations (local, online). The results vary widely, and are likely sensitive to the specifics of hardware, cpu cores, browser implementation, etc. But in general, this package is more performant than hcluster.js, to varying degrees, and is always at least as performant on average. Chrome seems to see the most performance gains (up to 10x, when the row number is high), while Firefox seems to see no gains.
  • This package does not touch the input data object, whereas the hcluster.js package does. D3 often expects you to mutate data objects directly, which is now typically considered bad practice in JavaScript. Instead, this package returns the useful data from the clustering algorithm (including the distance matrix), and allows you to mutate or not mutate the data object depending on your needs.
  • This package leaves out the minDistance or maxDistance functions that are built into hcluster.js, because -- per this reference -- they are not as effective as averageDistance.

Making changes to the library

  1. Install Node
  2. Install Yarn
  3. Clone this repo and navigate to it in your command terminal
  4. Run yarn install to install this package's dependencies
  5. Make desired changes to ./src/hclust.js
  6. Run yarn test to automatically rebuild the library and run test suite
  7. Run yarn build to just rebuild the library, and output the compiled contents to ./build/hclust.min.js
  8. Commit changes to repo if necessary. Make sure to run the build command before committing; it won't happen automatically.

Similar libraries

cmpolis/hcluster.js harthur/clustering mljs/hclust math-utils/hierarchical-clustering


Further reading

The AGNES (AGglomerative NESting) method; continuously merge nodes that have the least dissimilarity.

版本与发布记录

@greenelab/hclust 共发布 3 个版本,首次发布于 2020/03/25;过去 12 个月发布了 0 个版本。

版本发布日期距今
0.0.1latest2020/11/265 年前
0.0.02020/03/256 年前
0.0.0-dev2020/03/256 年前

关于 @greenelab/hclust 的常见问题

@greenelab/hclust 是什么?

Agglomerative hierarchical clustering in JavaScript

如何安装 @greenelab/hclust?

在项目目录运行 npm install @greenelab/hclust,或使用 pnpm add / yarn add / bun add。

@greenelab/hclust 支持 TypeScript 吗?

该包的 package.json 没有声明类型入口。需要类型提示时,可以在 npm 上查找社区维护的 @types/greenelab__hclust 是否存在。

@greenelab/hclust 支持 ESM 还是 CommonJS?

同时提供 ES Module 与 CommonJS 入口,import 和 require() 都可以使用,打包工具会自动选择合适的版本。

@greenelab/hclust 可以商用吗?

@greenelab/hclust 使用 MIT 许可。宽松许可:允许商业使用、修改和再分发,通常只需在分发时保留原版权与许可声明。以上为概括,不构成法律意见,请以许可原文为准。

@greenelab/hclust 的下载量有多少?

根据 npm 官方下载统计,@greenelab/hclust 在 2026/10/17 – 2026/11/15 这 30 天内被下载 5,623 次,日均约 187 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入,适合横向比较热度,不能直接等同于使用人数。

@greenelab/hclust 还在维护吗?

最新版本 0.0.1 发布于 2020/11/26(5 年前);至今共发布 3 个版本,其中过去 12 个月发布了 0 个;首次发布于 2020/03/25。发布频率只是参考信号:功能稳定的工具可能很少需要更新,建议结合源码仓库的 issue 和提交记录判断。