Aioli

Aioli is a framework for building fast genomics web applications using WebAssembly and WebWorkers.

Tools using Aioli

Getting Started

As shown below, you can obtain Aioli from our biowasm CDN, or you can install it from npm: npm install @biowasm/aioli (use the npm option if you need to host the Aioli module locally).

A simple example

Here's Aioli in action running the genomics tool samtools on a small SAM file:

<script src="https://cdn.biowasm.com/aioli/latest/aioli.js"></script>
<script>
let samtools = new Aioli("samtools/1.10");

document.write("Loading...");
samtools
    // Initialize samtools
    .init()
    // Run "samtools view" command with "-q 20" filter
    .then(() => samtools.exec("view -q 20 /samtools/examples/toy.sam"))
    // Output result
    .then(d => document.write(`<pre>${d.stdout}\n${d.stderr}</pre>`));
</script>

Working with user files

We can update the previous example to run samtools on a file provided by the user:

<input id="myfile" type="file" multiple>

<script src="https://cdn.biowasm.com/aioli/latest/aioli.js"></script>
<script>
let samtools = new Aioli("samtools/1.10");

// Initialize samtools and output the version
samtools
    .init()
    .then(() => samtools.exec("--version"))
    .then(d => console.log(d.stdout));

// When a user selects a .sam file from their computer,
// run `samtools view -q20` on the file
function loadFile(event)
{
    Aioli
        // First mount the file
        .mount(event.target.files[0])
        // Once it's mounted, run samtools view
        .then(f => samtools.exec(`view -q20 ${f.path}`))
        // Capture output
        .then(d => console.log(d.stdout));
}
document.getElementById("myfile").addEventListener("change", loadFile, false);
</script>

Aioli Configuration

Simple

// -------------------------------------
// Format: <module>/<version>
// -------------------------------------

// Retrieve specific version (recommended for stability)
new Aioli("seqtk/1.2");

// Retrieve latest version
new Aioli("seqtk/latest");


// -------------------------------------
// Format: <module>/<program>/<version>
// -------------------------------------

// For most bioinformatics tools, <module> == <program>
new Aioli("seqtk/seqtk/1.2");

// But not always! Some tools have multiple sub-tools
new Aioli("seq-align/smith_waterman/1.2");
new Aioli("seq-align/needleman_wunsch/1.2");

Advanced

By default, Aioli retrieves the .wasm modules and the Aioli WebWorker code from the biowasm CDN for convenience, but you can also load files from local sources:

new Aioli({
    module: "seq-align",
    program: "smith_waterman",              // optional (defaults to $module)
    version: "latest",                      // optional (defaults to latest)
    urlModule: "./path/to/wasm/files/",     // optional (defaults to biowasm CDN)
    urlAioli: "./path/to/aioli.worker.js",  // optional (defaults to biowasm CDN)
});

Background info

What is WebAssembly?

WebAssembly is a fast, low-level, compiled binary instruction format that runs in all major browsers at near native speeds. One key feature of WebAssembly is code reuse: you can port existing C/C++/Rust/etc tools to WebAssembly so those tools can run in the browser.

What is a WebWorker?

WebWorkers allow you to run JavaScript in the browser in a background thread, which keeps the browser responsive.

Compiling into WebAssembly

See the biowasm project.