jsAgrum v0.1: Graphical Models in the Browser

jsAgrum v0.1.X are BETA VERSIONS and still under active development. Some features are unimplemented and there may be bugs. Please file issues if you find them and/or submit feedback using our Feedback form. Thank you for testing jsAgrum!

jsAgrum wraps the capabilities of the aGrUM C++ Bayesian reasoning library for node- and web-based environments. jsAgrum is intended to support in-browser creation and inference of Bayesian Networks, meaning that the resulting models can be manipulated on any device or browser completely independent from hardware. jsAgrum also ensures reliability and security by executing all operations within the browser, eliminating server dependencies or the transfer of confidential data over a network. Complete support for TypeScript is included.

npm install jsagrum

The aGrUM library, the backbone behind jsAgrum, can quickly perform computationally intensive work using optimized algorithms and parallelization. jsAgrum brings this capability to the JavaScript environment by compiling aGrUM to Web Assembly. Different backends are available depending on user preferences:

• inProcessBN: runs computation directly on the main thread, sans parallelization. It is the only available backend for Node and usually the best choice for small networks.
• workerBN: runs single-threaded computation on a web worker attached to the main process. Longer computation does not block the main thread, and there are less restrictions compared to parallelized execution.
• parallelBN [NOT YET IMPLEMENTED]: runs multi-threaded computations on multiple web workers. It is the fastest backend for heavy computation, but has strict requirements on COEPS/COORS headers for websites and thus may present incompatabilities with other APIs.

Performance

Web Assembly is unavoidably slower than native code. The inProcessBN backend is roughly 3-4x slower than native C++ execution, while workerBN is roughly 8-10x slower. Detailed results are available by executing benchmarking in the bench folder. There are minor performance differences depending on whether the inProcessBN backend is ran on browser or in Node.

Above: Performance averaged over 20 runs of creating a Bayesian Network using FastBN syntax as a function of node count.

Above: Performance averaged over 20 runs of performing inference on a Bayesian Network as a function of node count.

Usage

To use the jsAgrum library, install the npm package and import one of the available factory methods (createInProcessBN, createWorkerBN, or the default createBayesNet). These factory functions will create a BayesNet object, which can then be manipulated using one of the many available member functions. Some select functions, such as getNode(), have a specialized return type in TypeScript.

Please note that the near entirety of available functions are asynchronous due to the nature of web workers.

import { createBayesNet } from 'jsagrum';
import type { BayesNet, BNNode } from 'jsagrum';

const bn: BayesNet = await createBayesNet();

const nodeId: number = await bn.addNode('Cloudy', 3, 200, 400)

bn.getNode(nodeId).then((n: BNNode) => {
  console.log("Retrieved node: ", n.name);
});

Documentation

Please visit our documentation for detailed information on available functions and to see examples!

Building from source

Prerequisites

• Node.js (v18+) — includes npm [ FOR BUILD AND TEST ]

  • Download from https://nodejs.org/
  • Verify: node --version and npm --version

• Emscripten (v4.0.21) — compiler toolchain [ FOR BUILD ONLY ]

  • Follow: https://emscripten.org/docs/getting_started/downloads.html
  • Verify: emcc --version

• CMake (v3.15+) [ FOR BUILD ONLY ]

  • macOS: brew install cmake
  • Linux: apt-get install cmake

The jsAgrum build script will automatically search for the emsdk — to maximize success, the emsdk repo should be within or share a common parent with jsAgrum.

Build, Test, and Document

$ cd jsagrum
$ npm install
$ npm test
$ npm run pages:build
$ npm run pages:serve

Documentation will be visible locally at port 4173. The build scripts have only been verified on MacOS.

The beta version of jsAgrum is incompatible with the latest release aGrUM version (2.3.1). We thus anchor jsAgrum to the most recent commit in the dev branch with a passing pipeline for both aGrUM and jsAgrum. The current commit is here. It is possible to instead specify a ref AGRUM_REF to the desired branch or commit SHA, or provide a path AGRUM_LOCAL to compile from a local copy. This will be resolved with the next release of aGrUM.

$ AGRUM_LOCAL=/path/to/aGrUM bash ./build_libagrum_mjs.sh

To enable debug logging, after initial install, call the build script with a debug flag. This replaces the libagrum.mjs and libagrum.wasm files only. In case of a high failed test count, run npm run test:libagrum to solely execute a minimal test suite on the emscripten-compiled module and thus pinpoint bugs at the root.

$ bash ./build_libagrum_mjs.sh -debug
$ npm test
$ npm run test:libagrum

Beta Version Notes

If you have general comments or requests for the jsAgrum, please use our Feedback form. We are actively working on the formal version 1 and would be thrilled to integrate your feedback!

To-do list for jsAgrum:

• Performance and size optimizations
• Implementation of parallel execution backend
• Function to permit moving between backends (i.e. move from inProcess to Worker)
• Further documentation and examples
• Expanded i/o support and additional file formats
• Possible separation of package into modules:
  • jsAgrum/training: Build and train Bayesian graphical networks.
  • jsAgrum/inference: Perform probabilistic inference based on Bayesian networks.
  • jsAgrum/causality: Build and train causal models.