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.
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.
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:
samtools view -H
only parses the header of the file.You can even mount URLs as long as they are CORS-enabled:
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.
Biowasm also supports running multiple tools at once. Below, we first run seqtk
on the output of a samtools
command:
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"]);
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)
});
// 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"
]);
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>
}]);
// 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 ls, cd, mkdir, pwd utilities
await CLI.mkdir("/some/path");
await CLI.ls("/some/path");
await CLI.cd("/some/path");
await CLI.pwd();
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
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:
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";
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.
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.