Apparatus Machine Learning Routines

Common errors

• TypeError: Class constructor KMeans cannot be invoked without 'new'

  cause Attempting to call the `KMeans` constructor (or similar algorithm classes) as a function without the `new` keyword.
  fix Instantiate the class using `const k_means = new KMeans();` instead of `const k_means = KMeans();`.

• Error: Cannot find module 'apparatus/lib/clustering/k_means'

  cause Incorrect import path or the 'apparatus' package is not installed correctly or is not accessible from the current working directory.
  fix Ensure 'apparatus' is installed (`npm install apparatus`) and verify the exact path `require('apparatus/lib/...')` matches the structure within `node_modules`. Paths are case-sensitive.

• SyntaxError: Cannot use import statement outside a module

  cause Attempting to use ES module `import` syntax (`import { KMeans } from 'apparatus/lib/...'`) in a Node.js environment that expects CommonJS modules.
  fix Replace `import` statements with CommonJS `require()` calls: `const KMeans = require('apparatus/lib/clustering/k_means').KMeans;`.

Warnings

• breaking The 'apparatus' package has been abandoned since its last commit in March 2012. It is not maintained and is highly unlikely to be compatible with modern Node.js versions (e.g., Node.js 14+). Expect runtime errors related to deprecated APIs, missing polyfills, or C++ native module incompatibilities if any are present.
  Fix: Avoid using 'apparatus' for new projects. Consider actively maintained alternatives like `ml-matrix`, `scikit-learn` (via Python bridge), or `tensorflow.js` for machine learning in Node.js.
• gotcha Apparatus relies exclusively on CommonJS `require()` syntax and is not designed for ES Modules (ESM). Attempting to use `import` statements will result in a `SyntaxError` unless a transpilation step (e.g., Babel) is configured or Node.js's `--experimental-modules` flag is used with care, which is not recommended for an abandoned library.
  Fix: Always use `const MyClass = require('apparatus/lib/path/to/module').MyClass;` for all imports.
• gotcha The package provides low-level numerical algorithms. It does not include features for natural language processing (NLP), image processing, or complex data pre-processing. Users are expected to prepare their data into arrays of numbers or vectors before passing them to apparatus algorithms.
  Fix: For text processing, consider the 'natural' package (which uses apparatus internally but adds NLP layers) or other specialized libraries. For other data types, perform necessary feature extraction and vectorization externally.
• deprecated Due to its abandonment, 'apparatus' lacks security updates, bug fixes, or performance improvements. Using it in production environments carries significant risks, including potential vulnerabilities or unexpected behavior with evolving JavaScript runtimes.
  Fix: Migrate to a currently maintained machine learning library. If migration is not immediately feasible, thoroughly audit the codebase for security concerns and isolate its usage to minimize risk.

Install

• npm install apparatus npm
• yarn add apparatus yarn
• pnpm add apparatus pnpm

Imports

• BayesClassifier
  wrong:

  import { BayesClassifier } from 'apparatus';
  import { BayesClassifier } from 'apparatus/lib/classifier/bayes_classifier';

  correct:

  const bayes = require('apparatus/lib/classifier/bayes_classifier');
  const classifier = new bayes.BayesClassifier();

  Apparatus uses deep CommonJS imports. The main `apparatus` module does not export algorithms directly.
• KMeans
  wrong:

  import { KMeans } from 'apparatus/lib/clustering/k_means';
  const KMeans = require('apparatus/lib/clustering/k_means');

  correct:

  const KMeans = require('apparatus/lib/clustering/k_means').KMeans;
  const k_means = new KMeans();

  Some modules export a named property, `KMeans` in this case. ESM imports are not supported.
• LogisticRegression
  wrong:

  import LogisticRegression from 'apparatus/lib/regression/logistic_regression';

  correct:

  const LogisticRegression = require('apparatus/lib/regression/logistic_regression').LogisticRegression;
  const regression = new LogisticRegression();

  Similar to KMeans, LogisticRegression is a named export from a deep path within the CommonJS module structure.

Quickstart

Demonstrates training a K-Means clustering model with sample 2D data, including setup and output of clusters and centroids.

const KMeans = require('apparatus/lib/clustering/k_means').KMeans;

// Sample data: each inner array is a data point (e.g., [x, y])
const data = [
  [1, 1], [1.5, 2],
  [5, 7], [8, 8],
  [1, 0.8], [9, 11]
];

const k_means = new KMeans();

// Configure K-Means algorithm
// k: number of clusters
// iterations: max iterations
// threshold: convergence threshold
k_means.k = 2;
k_means.iterations = 100;
k_means.threshold = 0.001;

// Train the K-Means model
k_means.train(data, (error, result) => {
  if (error) {
    console.error('K-Means training error:', error);
    return;
  }
  console.log('K-Means Clusters:');
  result.clusters.forEach((cluster, index) => {
    console.log(`  Cluster ${index + 1} Centroid: [${cluster.centroid.join(', ')}]`);
    console.log(`  Points in Cluster ${index + 1}:`, cluster.points);
  });
});