Heta-compiler NPM

Heta compiler

Heta compiler is a software tool for the compilation of Heta-based QSP modeling platforms. Heta compiler can also be used as a JavaScript/Node package to develop modeling tools.

To read the full documentation, visit the Heta project homepage: https://hetalang.github.io/#/heta-compiler/.

Introduction

Heta compiler is a tool for the development of Quantitative Systems Pharmacology and Systems Biology platforms. It allows combining modules written in different formats like: Heta language code, Excel sheets, JSON/YAML formatted structures, SBML and transforming them into the dynamical model/models of different formats.

Quantitative Systems Pharmacology (QSP) is a discipline that uses mathematical computer models to characterize biological systems, disease processes and drug pharmacology. QSP typically deals with mechanism-based dynamical models described by ODE systems. Sometimes the modeling systems includes hundred or thousand of components and developed by a research group involving people with different expertise.

Heta compiler can be used as the framework for a QSP modeling project of any size and complexity. It can be easily integrated with existed infrastructure, workflows or used as a part of the CI/CD strategy. The pre-formulated requirements of Heta compiler are:

storing the QSP models and data in integrated infrastructure;
support iterative modeling platform updates (continuous development approach);
support of models written in human-readable text and table formats;
export models and data to different popular formats on the fly.

How to cite

Metelkin, E., (2021). Heta compiler: a software tool for the development of large-scale QSP models and compilation into simulation formats. Journal of Open Source Software, 6(67), 3708, DOI: 10.21105/joss.03708

Installation

Installation in Windows

Download -win-x64-installer.msi from release page and install.

Installation in Linux and Macos

For all users (requires sudo previleges)

# replace [Required version] by value, i.e. 0.8.1
sudo wget -O /usr/local/bin/heta https://github.com/hetalang/heta-compiler/releases/download/[Required version]/heta-compiler-linux-x64 && sudo chmod +x /usr/local/bin/heta

For single user without sudo previleges

# replace [Required version] by value, i.e. 0.8.1
mkdir -p ~/bin
wget -O ~/bin/heta https://github.com/hetalang/heta-compiler/releases/download/[Required version]/heta-compiler-linux-x64
chmod +x ~/bin/heta
echo "export PATH=$PATH:~/bin" >> ~/.bashrc
source ~/.bashrc

Installation in NodeJS environment

NodeJS must be installed prior to Heta compiler installation. Currently the recommended version is NodeJS v16 and newer, but NodeJS v14 is also supported.

The next steps should be taken using console (shell): cmd, PowerShell, sh, bash depending on your operating system.

Check Node version.
```
node -v
# must be v14.0.0 or newer
```
The latest stable version of Heta compiler can be installed from npm
```
npm i -g heta-compiler
```
OR The development version can be installed directly from GitHub
```
npm i -g git+https://github.com/hetalang/heta-compiler.git
```

Supported tools

for more information see export formats

Heta compiler was created to support exporting to different popular modeling formats. One of the main development effort is to extend a list of supporting formats and allow people to have the same results working in different tools. The current version supports the following formats:

DBSolveOptimum .SLV files link
SBML L2V4 link
mrgsolve .CPP files link
Simbiology/Matlab .M files link
Matlab describing ODEs file link
Julia format
JSON formatted file
YAML formatted file
Excel sheets

Usage of command line interface

Heta compiler comes with a built-in CLI which can be used to compile files from the command line.

To learn more about options, see CLI references

The following is the example where we create a Heta module and compile it into SBML format. For example you want to create platform in directory "/path/to/my-platform" (target directory)

Create Heta file: index.heta in the target directory with the content:

comp1 @Compartment;
s1 @Species { compartment: comp1 };
r1 @Reaction { actors: s1 => };

comp1 .= 1;
s1 .= 10;
r1 := k1*s1*comp1;
k1 @Const = 1e-2;

#export {
    format: SBML,
    filepath: model
};

Be sure you are in the target directory, use command cd /path/to/my-platform or similar if not. Compile the platform:
```
heta build
```
Heta builder takes "index.heta" file (module) as default, reads it and transforms to SBML file as declared in index.heta.
See results of compilation in directory /path/to/my-platform/dist.

If you would like to load the platform form several files using include statement inside "index.heta", see specifications.

Creating a Heta platform template

Platform can be structured using a prepared template of folders and pre-constructed embedded files. Heta compiler provides the heta init tool for creating a such a modeling platform template.

The tool creates a draft platform including supplementary files and directories including the platform.js file, and files for git repository.

For more information see the CLI references documentation.

heta init
$ heta init
Creating a template platform in directory: "Y:\draft"...
? Platform id (template) draft
? Platform id draft
? Platform notes (platform notes)
? Platform notes platform notes
? Platform version (v0.1.0)
? Platform version v0.1.0
? Platform license (UNLICENSED)
? Platform license UNLICENSED
? Set options (y/N)
? Set options No
? Select file types (Use arrow keys)
> heta
  heta+xlsx
  heta+xlsx extended
  xlsx
  json
  yaml

Usage in NodeJS packages

Heta compiler has been written in NodeJS environment and can be used as a package for browser or server-side tools and applications.

To learn more more, see API docs (under development).

const { Container } = require('heta-compiler');

// platform code in Q-array format
let qArr = [
    { class: 'Compartment', id: 'comp1', assignments: {start_: '1'} },
    { class: 'Species', id: 's1', compartment: 'comp1', assignments: {start_: '10'} },
    { class: 'Reaction', id: 'r1', actors: 's1 =>', assignments: {ode_: 'k1*s1*comp1'} },
    { class: 'Const', id: 'r1', actors: 's1 =>', num: 1e-2 },
    { action: 'export', format: 'SBML', filepath: 'model' }
];

// compilation
let c = (new Container)
    .loadMany(qArr)
    .knitMany();
// get export element
let output = c.exportStorage[0]
    .make();

// print sbml code to console
console.log(output[0].content);

// check errors
console.log(c.hetaErrors());

Known issues and limitations

To see a list of the supported format features, go to features support table.

The tool is under active development so there are a lot of features to implement. To help us prioritize them write an issue.

Getting help

Read Heta documentation on https://hetalang.github.io/
Use Gitter Chatroom.
Use Issue Tracker

Contribute

Source Code
Issue Tracker
See also contributing in Heta project

License

Licensed under the Apache License, Version 2.0. See the LICENSE text.

Authors and history

The original author of the project is Evgeny Metelkin. The tool was inspired by the idea that large scale dynamical systems used in QSP and SB require the specific tool which allows writing model code in unified formats and transforming them depending on one's needs: to database-like format or ODEs. Working with large models should be as easy as with the small ones.

The initial prototype 0.1.x was developed in 2017 and named as qs3p (quantitative systems pharmacology programming platform). It was used in several InSysBio LLC projects including IRT and Alzheimer disease consortium.
The next versions of qs3p-js used the updated format of platform components and a new approach for storing them. A set of new exporting formats was supported. The current version supports Heta code including actions, modules, namespaces. It was used as the main infrastructure for the development of the large- and middle-scale QSP platforms developed in the framework of InSysBio services.
In 2020 the tool was renamed to Heta compiler and published as a Free Open Source project on GitHub under Apache 2.0 license. Since then Heta compiler has been developed in the framework of Heta project.