libsbmljs — Enabling Web–Based SBML Tools

The SBML standard is used in a number of online repositories for storing systems biology models, yet there is currently no Web–capable JavaScript library that can read and write the SBML format. We present libsbmljs, a JavaScript / WebAssembly library for Node.js and the Web with full support for all SBML extensions. Our library is an enabling technology for online SBML editors, model–building tools, and web–based simulators. We provide NPM packages, an extensive set of examples, JavaScript API documentation, and an online demo that allows users to read and validate the SBML content of any model in the BioModels and BiGG databases. We also provide instructions and scripts to allow users to build a copy of libsbmljs against any libSBML version. Although our library supports all existing SBML extensions, we cover how to add additional extensions to the wrapper, should any arise in the future. Our project is hosted at https://libsbmljs.github.io/, which contains links to examples, API documentation, and all source code files and build scripts used to create libsbmljs. Our source code is licensed under the Apache 2.0 open source license. The online demo is available at https://libsbmljsdemo.github.io/.


Introduction
The SBML (1) standard is used for encoding reaction network models in systems biology research in a reusable, exchangeable, and future-proof manner. One of the factors behind SBML's wide adoption is the SBML standard's process for introducing extension modules, which allow incremental incorporation of new capabilities. While the core components of the standard are designed for describing kinetic chemical reaction network models, SBML extensions exist for encoding constraint-based models (the "fluxbalance constraints" extension, employed by the widely used COBRA framework for constraint-based modeling (2, 3)), and rule-based models (the SBML "multi" extension (4)). SBML is used in several online model repositories including BioModels (5? ) and JWS Online (6,7), which host primarily kinetic reaction network models, and BiGG Models cite (8), which hosts primarily genome-scale constraint-based models. Despite this wide-spread adoption and inclusion in several online repositories, no feature-complete JavaScript library currently exists that can run in a web browser (a native Node.js module exists, but cannot run in the browser). Thus, these online repositories must rely on server-side processing of all SBML-related requests. A JavaScript library would allow these services to offload some of their processing to the client, and would also allow for more interactive features on the Web. Furthermore, the Web is becoming a major platform for systems biology tools. With the advent of Web applications for pathway visualization (Escher (9)), gene interaction network visualization (Cytoscape.js (10)), expression analysis (ZBIT (11)) and integrated design systems (Caffeine (12)), the need for a JavaScript library which can read and write SBML becomes imperative. We present libsbmljs, a feature-complete JavaScript library for reading and writing SBML in the browser and Node.js. libsbmljs uses the full codebase of the libSBML C++ library compiled to the web using Emscripten, a toolset for compiling C++ projects to the web. Emscripten emits We-bAssembly (13), a W3C standard for running platformindependent binary code on the web that is supported on all major browsers. We have designed a JavaScript wrapper around this binary format that allows libsbmljs to be used like a normal JavaScript library. Our wrapper supports all SBML Level 3 extensions, meaning it can read and write any type of SBML content. Since our library runs in the browser, it does not require a dedicated web server. This is an important consideration for academic software, where long-term maintenance cost is a concern.
Methods Prior work on implementing the SBML standard has resulted in two libraries: libSBML (14), a C++ library with interfaces for many languages, and JSBML (15,16), a platformindependent pure Java library. While the existence of these separate implementations is certainly a convenience for C++ and Java developers respectively, it necessitates the maintenance of two independent libraries. Rather than attempt to create a third implementation in pure JavaScript, we have created a web-capable interface for the libSBML C++ library using Emscripten (17), a C++-to-JavaScript compiler. Despite its C++ origins, libsbmljs is completely platform independent and runs on modern browsers on any device which supports web standards. Compiling a C++ library with Emscripten does not produce a ready-to-use JavaScript library automatically. Instead, Emscripten compiles to WebAssembly (18), a low-level binary format similar to x86 machine code but with additional features for security and platform-independence. Since We-bAssembly is very low level, it is difficult to use to design JavaScript web applications. Instead, Emscripten can be used to also compile a JavaScript interface that abstracts the lowlevel details of calling into WebAssembly and instead allows developers to use familiar JavaScript objects and methods. However, this interface is not generated automatically by Em-D R A F T scripten. Instead, it must be manually specified using We-bIDL. Web IDL is a World Wide Web Consortium (W3C ® ) standard that specifies interfaces to EMCAScript (i.e. JavaScript) objects. For example, the libSBML C++ class SBase has the method getId(), which returns a string. In WebIDL, this would be specified as: In the example above, the body of the getId method is intentionally left blank because it will delegate to the corresponding WebAssembly routine. Using syntax similar to the above, we manually designed WebIDL interface files for every libSBML class and method. However, one issue remains with this approach. The comments entered into the IDL definition above will not appear in the JavaScript interface generated by Emscripten. Thus, there is no way of adding documentation to the generated JavaScript code, which defeats any attempt to generate API documentation. To remedy this issue, we created a script to automatically extract documentation strings from IDL files and insert them into the generated JavaScript code. This allowed us to generate extensive API documentation using documentationjs, a documentation generator for JavaScript.

Special
Considerations for Usage. Emscriptengenerated WebAssembly/JavaScript libraries are supported on a wide variety of browsers and devices (https://github.com/libsbmljs/libsbmljs lists the browsers we have tested). However, there are minor differences between these libraries and regular JavaScript libraries, which are described below.
Asynchronous Loading. Emscripten-generated libraries load asynchronously. In other words, the library cannot be used immediately as soon as the web page has loaded. This is due to the fact that Emscripten-generated libraries consist of both a JavaScript source file (.js) containing JavaScript classes and methods, and a WebAssembly file (.wasm) containing the compiled C++ code. The browser may load the JavaScript source file before completely loading and compiling the We-bAssembly file. In order to accommodate this, Emscripten libraries provide a 'then()' method for the JavaScript module object similar to a JavaScript Promise. This method accepts a callback that will execute once the WebAssembly is fully downloaded and compiled.
Manual Memory Management. Most modern languages feature some type of automatic garbage collection. However, WebAssembly is a low-level binary-like format, and hence does not provide high-level features like garbage collection. This means that whenever the user creates an object in libsbmljs using the new keyword, the user must also destroy the object using libsbml.destroy(obj). In most cases, this simply amounts to destroying the SBML document when it is no longer needed. In terms of modern programming languages, this may seem like a significant regression, but it is an unavoidable tradeoff when using C++ compiled WebAssembly, at least for currently available technology (a proposal exists to add garbage collection to WebAssembly (19), but an implementation is not available at the time of writing). In the event that the user forgets to call the libsbml.destroy function, the allocated object will persist in the browser's memory until the browser tab is closed. Since our main target users are developers of web applications, and browser tabs are short-lived, we do not believe this is a significant concern. However, Node.js developers should take care to destroy all created objects. The same requirement also applies to libSBML's native Node.js module.

Discussion & Conclusion
Currently, there is no web-capable library that can read and write SBML models. We have presented a WebAssembly / JavaScript library that can read and write all SBML packages. We have provided tutorials, examples and extensive API documentation for potential users. We have also provided a modular build system that can be used to regenerate the wrapper from any recent checkout of the libSBML C++ library from the stable or experimental branch, as well as inbrowser tests of the wrapper using the Karma testing engine. We hope this wrapper will enable the development of systems biology web applications and services that can use the SBML standard.  (12) Species (6) Compartments (1) Parameters (16) Events (0) Functions (0) Rules (9) Checks for measurement units associated with quantities  Fig. 1. (A) A workflow diagram of the process used to produce libsbmljs. The lib-SBML C++ source code and a hand-written WebIDL interface are processed by a Gradle script to produce Emscripten-compiled bytecode and JavaScript API documentation. The Emscripten bytecode is further compiled into separate JavaScript (*.js) and WebAssembly (*.wasm) files. When the JavaScript source file is loaded by the browser, it executes instructions to fetch the corresponding WebAssembly file asynchronously. These two files are then combined into an npm package.

(B)
A screenshot of the demo page showing the Repressilator model (20) in the BioModels database (BIOMD0000000012). After selecting a model via using the demo's search bar or uploading an SBML file, the demo allows the user to view SBML content as a tree-like structure and validate the SBML model subject to the validation options provided by libSBML. This particular model can be viewed at https://libsbmljsdemo.github.io/#/view?m=BIOMD0000000012