Density Based Clustering Algorithms

1.3.0 · maintenance · verified Sun Apr 19

This JavaScript package provides implementations of popular cluster analysis algorithms, including DBSCAN (Density-Based Spatial Clustering of Applications with Noise), OPTICS (Ordering Points To Identify the Clustering Structure), and K-Means. Currently at version 1.3.0, the package appears to be in a maintenance state, primarily supporting CommonJS environments as indicated by its examples and `bower` installation instructions, which suggest it hasn't fully adopted modern ESM practices or aggressive development cycles. A key differentiator is its direct, unopinionated implementation of these core algorithms for data mining and statistical analysis. While DBSCAN and OPTICS are true density-based methods, K-Means is included for broader utility, though it's important to note it does not rely on density for clustering. The library focuses on providing these fundamental tools for data scientists and developers working with clustering tasks.

Common errors

```
ReferenceError: require is not defined
```
cause Attempting to use `require()` in an ECMAScript Module (ESM) context without proper transpilation or configuration.

fix Ensure your Node.js project is configured for CommonJS (e.g., `"type": "commonjs"` in `package.json` or by using `.cjs` extension for files). For browser environments, use a bundler.
```
TypeError: clustering is not a constructor
```
cause Incorrectly trying to instantiate `new clustering()` instead of `new clustering.DBSCAN()` (or OPTICS/KMEANS).

fix Access the specific clustering algorithm class (e.g., `DBSCAN`, `OPTICS`, `KMEANS`) as a property of the `clustering` object before instantiating it, like `new clustering.DBSCAN()`.
```
Error: Invalid parameters for algorithm run.
```
cause Providing an incorrect number or type of arguments to the `run` method of DBSCAN, OPTICS, or KMEANS.

fix Refer to the documentation for the specific algorithm's `run` method. DBSCAN and OPTICS typically expect `(dataset, neighborhoodRadius, minPoints)`, while KMEANS expects `(dataset, numberOfClusters)`.

Warnings

gotcha When using the OPTICS algorithm, the initial `clusters` array returned by `run()` is often nearly identical to DBSCAN's output. To fully leverage OPTICS for varying densities and hierarchical structures, you *must* analyze the `reachability plot` generated by `optics.getReachabilityPlot()`.
Fix: After running OPTICS, call `optics.getReachabilityPlot()` and implement logic to interpret the plot for multi-density or hierarchical cluster extraction as per the OPTICS algorithm specification.
gotcha The K-MEANS algorithm is included in this library but it is *not* a density-based clustering method. Its inclusion is for completeness, but users should be aware that it operates on different principles (centroid-based partitioning) compared to DBSCAN and OPTICS.
Fix: Understand the fundamental differences between K-Means and density-based algorithms. Use K-Means when partitioning into a predefined number of clusters is desired, rather than identifying dense regions and noise.
deprecated The documentation mentions `bower install density-clustering` for browser usage. Bower is largely deprecated and not recommended for modern web development. Using `npm` with a bundler (like Webpack or Rollup) is the current standard for browser integration.
Fix: For browser use, install via `npm install density-clustering` and then use a JavaScript bundler (e.g., Webpack, Rollup, Parcel) to include it in your browser-side application.

Install

npm install density-clustering npm
yarn add density-clustering yarn
pnpm add density-clustering pnpm

Imports

DBSCAN
wrong:
```
import { DBSCAN } from 'density-clustering';
```
correct:
```
const clustering = require('density-clustering');
const dbscan = new clustering.DBSCAN();
```
The library primarily uses CommonJS `require` syntax. Direct ESM named imports may not work without a bundler or transpiler setup for older modules.
OPTICS
wrong:
```
import OPTICS from 'density-clustering/optics';
```
correct:
```
const clustering = require('density-clustering');
const optics = new clustering.OPTICS();
```
Classes are exposed via the main `clustering` object. Importing from subpaths or using default imports is not supported.
KMEANS
wrong:
```
const KMEANS = require('density-clustering').KMEANS;
```
correct:
```
const clustering = require('density-clustering');
const kmeans = new clustering.KMEANS();
```
While this specific `wrong` example might technically work, the recommended pattern is to get the `clustering` object first and then access its properties for consistency.

Quickstart

Demonstrates how to initialize and run the DBSCAN algorithm on a sample dataset, logging the identified clusters and noise points.

const dataset = [
    [1,1],[0,1],[1,0],
    [10,10],[10,13],[13,13],
    [54,54],[55,55],[89,89],[57,55]
];

const clustering = require('density-clustering');
const dbscan = new clustering.DBSCAN();
// parameters: 5 - neighborhood radius, 2 - number of points in neighborhood to form a cluster
const clusters = dbscan.run(dataset, 5, 2);
console.log('Clusters:', clusters);
console.log('Noise points:', dbscan.noise);

/* Expected Output:
Clusters: [
    [0,1,2],
    [3,4,5],
    [6,7,9]
]
Noise points: [ 8 ]
*/

view raw JSON →