Skip to content

sys-bio/vscode-antimony

Repository files navigation

Antimony for Visual Studio Code

MIT License

The Antimony extension adds language support for Antimony to Visual Studio Code for building models in Systems Biology.

The currently available version 0.2 is a public beta version developed by Longxuan Fan, Sai Anish Konanki, Eva Liu, Steve Ma, Gary Geng, Dr. Joseph Hellerstein, and Dr. Herbert Sauro at the University of Washington. Dr. Joseph Hellerstein is responsible for future releases, and please feel free to contact him if you have any questions.

Please note that the current release does not support the complete Antimony grammar. While most grammar has been supported, more will be included in future releases. Flux balance constraints and submodeling are not supported currently.

Installation (Required)

The Antimony Extension Pack is available on the Visual Studio Code Extensions Tab and the Visual Studio Code Marketplace. (We recommend installing the extension pack directly so you have full access to all of the features.)

Windows Instructions  |  Mac Instructions  |  Linux Instructions

Windows

  • This extension requires Vscode Antimony Dependencies Installer to be installed.
  • Your web browser may warn that this isn't a commonly installed software, allow the browser to keep the download.


(Press Keep)

  • Once Vscode Antimony Dependencies Installer is installed, open the Downloads folder on your device
  • Double click "Vscode Antimony Dependencies Installer" to start the setup process. If there is a warning pop up from Windows, click more info and then click run anyway. (This will not intefer with any other dependencies and programs of your device).


(Press more info)


(Press run anyway)

  • Once installed, restart Visual Studio Code if you have Visual Studio Code already installed. Otherwise, proceed. Next Steps Below

Mac

  • This extension requires Vscode_Antimony_Setup (Silicon CPU Macbooks) or Python 3.9.13 (Intel Macbooks) to be installed before use.
  • For Intel CPU Macbooks: When installing Python 3.9.13, proceed with the installations as is. No changes are needed to be made.
  • For Silicon CPU Macbooks: When installing Vscode_Antimony_Setup.pkg, right click on the pkg file and press open.


(Right click, then press open)

  • For Silicon CPU Macbooks: Click open when the pop up appears.


(Click open)

  • Once installed, restart Visual Studio Code if you have Visual Studio Code already installed. Otherwise, proceed.
    Next Steps Below

Linux

  • Linux users will have to install Python3.10, venv python package, and pip.
  • Once installed, restart Visual Studio Code if you have Visual Studio Code already installed. Otherwise, proceed.
    Next Steps Below

Steps below apply for all Operating Systems

  • If there are any non VSCode Antimony associated virtual environments activated, please deactivate them before setting up VSCode Antimony.
  • Install Git. Make sure to add Git to PATH when installing if the option shows. Restart Visual Studio Code if already installed after installation of Git.
  • Install VSCode for your specific operating system (Mac, Windows, or Linux)
  • Once you open VSCode, download the Antimony Extension Pack from the Visual Studio Code Extension Marketplace and install. This should install Antimony and Antimony Syntax. Follow the numbered points in the figure below.


(Download Antimony Extension)

  • When an XML or Antimony model file is opened for the first time, a pop up will show. On the other hand, if a user does not have a SBML or Antimony file, they can open the Command Palette (Ctrl + Shift + P for Windows, Cmd + Shift + P for Mac) and type Open Antimony Start Page. This will open a simple Antimony page, which will allow for the installation of the virtual environment.


(Pop up for setup)


(Open Antimony Start Page)

  • Click yes to allow creation of virtual environment and installation of required dependencies. Click no to use your own default python interpreter (You can change the Vscode-Antimony python interpreter in the VSCode Settings in section Extensions/vscode-antimony. Use (Cmd + ,) for Mac and (Ctrl + ,) for Windows).


(Permissions for Virtual Environment Setup)

  • If there are errors during/after the installation, clear the error prompts--if there are any--on the bottom right corner, right click on the ant/xml file and press "Delete Virtual Environment". Attempt to restart VSCode or your device before clicking yes to the installation prompt again. If errors still occur, it is advices to press "Delete Virtual Environment" a second time.


(Error Fix)

  • A pop up may show if the incorrect python version is installed. Click yes, install the correct python version per instructions above and restart VSCode.



(Python Version Error)

  • Now, right clicking anywhere in the .ant file will display a list of features that can be accessed by users.


(List of options when right clicking in the file)

Features

The extension provides many convenient features for developing biological models with the Antimony language in tellurium. The current release focuses on the areas below.

1. SBML to Antimony Conversion and Editing


(SBML to Antimony conversion)

When an SBML file is opened, the editor will automatically convert the SBML file to the Antimony format. User can edit the Antimony file, and save the changes made to the Antimony model back to the original SBML file. ⚠️ Note: this feature can be disabled in settings


(Diagram of workflow)

2. Browsing Biomodels

The extension allows a user to browse for different biomodels from the BioModels database. The user can query for models with a string or a model number. The chosen model will be displayed in Antimony, which can be saved as SBML or Antimony.


(Biomodel Browsing with saving)

3. Syntax recognition and highlights


(Syntax Highlights)

⚠️ Note: the default syntax highlighting for Antimony is provided by a separate extension Antimony Syntax, and is also available in the Antimony Extension Pack

4. Automatic annotation creation with database recommendation

The extension can recognize different types of variables, and recommend databases based on the OMEX metadata specification.


(Creating an annotation of species BLL through the ChEBI database)

5. Hover messages


(Hovering over species to look up information)

6. Code navigation


(Navigating to the definition code)

7. Error detection

The extension supports various warning and error detections to help modelers debug their model during development. Our design principle for whether an issue should be a warning or an error entirely depends on the logic of tellurium. Our extension will mark the subject as an error if tellurium throws an error while rendering the model, with a red underline. An example would be calling a function that does not exist (usually due to a typo, which is extremely common during development. Read more in my thesis).


(Typos are extremely common in software development)

On the other hand, certain issues are not errors in tellurium, but we thought it would be worthwhile to have the user's attention. For example, missing initial values for species and overriding a previously defined value.


(Forgetting to initialize the value for a species, causing tellurium to assume a default value)

The extension supports a wide range of errors and warnings, and we plan to support more in the upcoming releases. Read more in issues.

8. Converter between Antimony and SBML


(Exporting Antimony file in SBML format)

9. Antimony/SBML preview


(Previewing Antimony file as SBML)

10. Automatic creation of rate laws


(Creating a rate law on a reversible reaction)

11. Annotation recommender for species


(Creating annotation for species BLL with Annotation Recommender)

12. Highlight indication for annotated species


(Displaying highlight indication for annotated species, BLL)

Known Issues

I have an open issue for manually curating models from BioModels to test the extension. Please feel free to contribute and submit issues.

  • subvariables in modular models are currently not supported and false error messages will be triggered.

Release Notes

0.1.0

  • First public release of the extension pack.

0.1.1

  • Added docs and examples.
  • Fixed an issue related to code navigation (#46).
  • Fixed an issue related to displaying hover message for annotated entities (#47).

0.1.2

  • Updated docs.

0.1.3

  • Updated docs.

0.1.4

  • Updated docs, included a list for updates in 0.2.

0.2.0

  • Added grammar support and warning/error detection for rate rules, sbo and cvterms, events, flux balance constraints, interaction, and import.
  • Converter between Antimony and SBML.
  • Antimony/SBML preview.
  • More databases supported in create annotation, and database recommendations.
  • Automatic creation of rate laws.
  • Annotation recommender for species.
  • Highlight indication for annotated species.

0.2.4

  • Automatic virtual environment installation.
  • SBML to Antimony Conversion and Editing.
  • Browsing Biomodels.

0.2.10

  • Minor bug fixes
  • Updated User Instructions