Documentation

Introduction

The biowasm project compiles popular C/C++ genomics tools to WebAssembly so they can run in a web browser. Biowasm includes a JavaScript library called Aioli that helps you run these tools with very little setup, as we'll see below.

Code Examples

A simple example

Say you're building a web app that analyzes sequencing data by parsing user-provided BAM files. On the command-line, you would use the program samtools to parse these files; with biowasm, you can write a few lines of code and run samtools directly in the browser:

Note that we ran samtools view on a sample file /samtools/examples/toy.sam that comes preloaded with biowasm for testing purposes.

Process local user files

To run samtools on a user-provided file (download one here), we need to mount the user's file onto a virtual file system before we can use it within Aioli:

Note: Mounting a file does not load its contents in memory! For example, selecting a 500GB BAM file below will work just fine since samtools view -H only parses the header of the file.

One common use case for biowasm is to efficiently process small subsets of large files in the browser, e.g. parse the very top/bottom of a file, or randomly subsample a large file.

Process remote user files

You can even mount URLs as long as they are CORS-enabled:

Note: Similar to local files, mounting URLs does not load their entire contents into memory. Below, we mount a 300MB BAM file and ask samtools for a small subset of chromosome 20. As you can see in your browser's Network tab, only a few megabytes of relevant data are downloaded for this step.

Run multiple tools

Biowasm also supports running multiple tools at once. Below, we first run seqtk on the output of a samtools command:

Aioli API

Initialization

Simple Initialization

Most tools can be initialized using a name and a version (see the Packages page for supported versions):

new Aioli(["samtools/1.10", "seqtk/1.3"]);

For tools that include multiple sub-tools, you need to specify which ones you want to load:

new Aioli(["coreutils/head/8.32", "coreutils/tail/8.32"]);

Advanced Initialization

If you need to customize the URL where the WebAssembly assets are stored, or the lazy-loading behavior of a module, you can use the following initialization format:

new Aioli([{
    tool: "coreutils",
    version: "8.32",
    program: "head",         // Optional: sub-tool name; not needed for most tools (default: same as tool name)
    urlPrefix: "./assets/",  // Optional: custom path to .wasm assets (default: biowasm CDN)
    loading: "lazy",         // Optional: if set to "lazy", only downloads WebAssembly modules when needed, not at initialization (default: eager)
    reinit: false,           // Optional: if set to true, will reinitialize module after each invocation; not needed for most tools
}], {
    printInterleaved: true,  // Optional: whether to return interleaved stdout/stderr; if false, returns object with stdout/stderr keys (default: true)
    debug: false,            // Optional: set to true to see console log messages for debugging (default: false)
});

Utility functions

Run a command

// Simple command
await CLI.exec("samtools view");

// To escape arguments, use an array instead of a string
await CLI.exec("jq", [
    ".some.data",
    "data.json"
]);

Mount local and remote files

See examples above for how to mount local files and remote URLs.

The function CLI.mount() can mount one (or an array of) File objects, Blob objects, a FileList, strings, or URLs:

// Mount a list of user-provided File objects
document.getElementById("myfiles").addEventListener("change", async event => {
    await CLI.mount(event.target.files);
});

// Mount URLs
await CLI.mount([
    { name: "filename.txt", url: "https://url..." },
    { name: "filename2.txt", url: "https://url2..." },
]);

// Mount a string to path filename.txt
await CLI.mount([{
    name: "filename.txt",
    data: "This is a data file"
}]);

// Mount a Blob to path filename.txt
await CLI.mount([{
    name: "filename.txt",
    data: <Blob>
}]);

File system utilities

// Returns a blob URL so the user can download a file out of the virtual file system
const url = await CLI.download("/path/to/a/file");

// Basic file system utilities
await CLI.mkdir("/some/path");
await CLI.ls("/some/path");
await CLI.cd("/some/path");
await CLI.pwd();

// Call Emscripten's virtual file system utilities (docs: https://emscripten.org/docs/api_reference/Filesystem-API.html)
await CLI.fs.unlink("/some/path/here"); // Delete a file
await CLI.fs.stat("/some/path/here"); // Get file size/timestamps

Note: File system utilities operate on a virtual file system; they cannot operate directly on user files.

Standard IO

If a tool needs to interact with stdin, set CLI.stdin before making the call to the tool:

CLI = await new Aioli(["coreutils/cat/8.32"]);
CLI.stdin = "Hello World";
await CLI.exec("cat");  // Will return Hello World

Biowasm without the CDN

The examples above use the biowasm CDN, which is where the WebAssembly assets for the genomics tools are hosted for free. Most tools that use biowasm rely on the CDN, but if you would like to store your assets alongside your app, here's how to do so:

Step 1: Install the Aioli package

Instead of importing Aioli using

<script src="https://biowasm.com/cdn/v3/aioli.js"></script>

you can install Aioli with npm:

npm install --save "@biowasm/aioli"

Then you can import Aioli as follows:

import Aioli from "@biowasm/aioli";

Step 2: Download Biowasm assets

Note that even if you import Aioli locally with npm, the WebAssembly modules will still be downloaded from the biowasm CDN unless you download those assets locally as well.

To do so, navigate to the Packages page and download the files for each tool of interest.

Step 3: Set up Aioli

Once your assets are downloaded, you need to let Aioli know the relative URL path where it can find those assets from your server. Use the config parameter urlPrefix as shown in the Initialization section above.