Nimble Porridge Muncher

    heta-compiler

    0.6.12 • Public • Published

    Heta project GitHub issues Autotests Coverage Status GitHub npm Documentation status GitHub license

    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/.

    Table of contents

    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

    NodeJS must be installed prior to Heta compiler installation. Currently NodeJS v8/v10 are recommended.

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

    1. Check Node version. It should be >= 8.0.0.

      node -v
      # v8.0.0 or newer
    2. 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)

    1. 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
      };
      
    2. 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.

    3. 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

    Contribute

    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.

    Copyright 2019-2021, InSysBio LLC

    Keywords

    none

    Install

    npm i heta-compiler

    DownloadsWeekly Downloads

    29

    Version

    0.6.12

    License

    Apache-2.0

    Unpacked Size

    5.03 MB

    Total Files

    331

    Last publish

    Collaborators

    • metelkin