SemanticSBML

SemanticSBML - user instructions

Introduction

Getting started

Main menu: the model list

Displaying a model

Adding and editing annotations in a model

Checking a model

Merging several models

Building a new model

Working easily with semanticSBML

Troubleshooting

Exercises

Introduction

There are two main ways to use semanticSBML: you can use it online at this website or install it locally on your computer. Please note that the online version provides only limited functionality: in particular, model merging in the online version works only for fully annotated and carefully prepared models. For serious applications, we suggest to use the installable version: it comes with a graphical user interface, but some of its functions are also available as scripts that can be run in the command line. To get to know semanticSBML, we suggest to start with the exercises listed on the end of this page.

Getting started

Installing semanticSBML

SemanticSBML can be freely downloaded from the download page and from sourceforge. It is written in python and runs on Linux, Windows, and OSX systems. On Linux systems, we recommend to use the debian package (.deb). You find the instructions for installation on the download page.

SemanticSBML uses the freely available program graphviz dot for visualizing networks. To use this option (called "View"), the program "dot" needs to be installed in your system, the path to the program has to be set in the "Configure" menu of semanticSBML (on linux systems, the shell command "which dot" will show you if and where dot is installed). In addition, the graphviz bin directory has to appear in your system path.

Running semanticSBML for the first time

When semanticSBML is started for the first time on your computer, it will download data (e.g., names and identifiers of chemical species) from several databases and save them in a hidden directory called ".semanticsbml" in your home directory (in the following simply called "data directory"). It is important that your computer is online when semanticSBML tries to download the data. In the command line, you will have to confirm that you agree with the license of the KEGG database. You can update these files at any time via the "Update now" button in the "Configure" tab in semanticSBML.

Main menu: the model list

In the main menu, you can load SBML models from disk into a model list (button "Open"). After selecting models from the list (by clicking), you can annotate, view, check, or merge them by clicking the respective buttons. To remove a model from the list, select it and press "Remove". To save a model, use "Save" or "Save as" in the "File" menu. A dot in the column "Modified" will indicate that the model has been changed.

In the online version, the main page shows the models in a table. Models can be added by uploading them ("Browse" and "Upload model"). After clicking on the model name, the SBML source code will be opened in a new tab. To view a model or to remove it from the list, click the respective links in the table. To annotate or check a model, click the links on top; you can then select a model. To merge several models, select them in the list and click the "merge" link.

back to top

Displaying a model

To visualize the model, select it in the main menu and press the "View" button. A network will be shown in a new window. Note that the program "dot" needs to be installed in your system (see above). In the online version, the graphics (in SVG format) will be shown in a new tab in your browser. Displaying the network can be numerically demanding and is therefore disabled for large models.

Adding and editing annotations in a model

In SBML, the biological meaning of model elements can be specified by annotations. In the SBML source code, there are two kinds of annotations: (i) annotation tags link an element to a database identifier (here, for brevity called "MIRIAM annotations"). The exact relationship between them is stated by a qualifier (in the most simple case, "Is"). (ii SBO terms linking an element to entries of the systems biology ontology (SBO). To annotate a model, you should be roughly familiar with the SBML format and with the two types of annotations (for information, see for instance www.sbml.org, the Systems Biology Ontology website and the Biomodels.net website).

To add or edit annotations, select the model in the main menu and press the "Annotate" button. This will open a new tab: on the left, you see an overview of the SBML model in form of a tree. If you select an element, detailed information about its annotations will appear on the right. Information about MIRIAM annotations and SBO terms is shown in two separate tabs.

Editing the MIRIAM annotations of a selected model element

In the MIRIAM tab, you can edit the MIRIAM annotations. Existing annotations are shown on top ("Current annotations"); here you can change the qualifier or remove the annotation. Below, you can add a new annotation: if you already know the database identifier, you can choose the database, the qualifier, and the identifier in the field "Add annotation" and directly add the annotation. If the identifier does not have the right syntax for the database (according to what is stated in the list_of_resources.xml file in the data directory), it will not be accepted.

For compartments, species, and reactions, you can also search for identifiers that match a serach term (in the field "Search annotation by name"). Type a search term (e.g. a metabolite name) in the "Search by name field" and press "search". SemanticSBML will present a number of possible annotations from which you can choose. The suggestions stem from a list of names and identifiers in the data directory.

Editing the SBO annotation of a selected model element

An SBML element can carry at most one SBO term. If you already know the SBO ID (e.g. "14" for the SBO term "enzyme") with which you want to annotate an element, you can set it directly (using the field "SBO ID"). You can also type the ID and press "more general" or "more specific" to move up or down in the SBO hierarchy. Upon pressing the button, possible SBO terms (with ID, name, and definition) will appear at the bottom. If you do not know a suitable SBO term yet, you can type a search string (e.g. "enzyme") in the field "Search term" to get suggestions.

General remarks about annotations

SemanticSBML can also insert MIRIAM annotations automatically. The automatic annotation is based on an exact string match between strings found in the SBML file (e.g., in the "name" fields) and the names in the database files. Note that despite the exact string match, automatically created annotations can be wrong, so they always should be checked by the user. To insert annotations in the entire model, select the root of the model tree "Model ..." and press the button "Annotate now". The automatic annotation will take some time. You can also run the automatic annotation for parts of the tree, e.g. only for species. In this case, select the node "Species" and press "Annotate now".

After you have annotated a model, the number of elements with missing annotation will be displayed in the model list in the main menu.

back to top

Checking a model

To run a number of consistency checks, select a model from the list in the main menu and press the "Check" button. A new tab "Checked models" with the results will open. To check a model in the online version, select it from the model list and click the "Check" link on top.

The consistency checks are as follows:

  1. Annotations: model elements are checked for MIRIAM annotations. If annotations are missing or cannot be interpreted, the following checks may miss some problems in the model.
  2. Duplicate elements: the model is checked for elements that are annotated with identical or equivalent database identifiers. The qualifiers are not considered.
  3. Overlapping compartments: compartments are checked for physical overlap according to their Gene Ontology annotations.
  4. Atom number balance: in a chemical reaction, atom numbers must be conserved. This constraint will be violated, for instance, if cofactors are not explicitly listed in the reaction; this will lead to a warning message.

The checks require that the model is fully annotated. If annotations are missing, this is reported by warning messages.

After checking a model, the number of errors found will be displayed in the model list. This number is updated when the model is checked again.

Note that the checking function concerns only the semantic validity of the model and works only for SBML model that are syntactically correct. For checking the syntactic correctness itself, we suggest to use the SBML online validator.

Merging several models

To merge two or models from the list, select them and press the "Merge" button. This will open a tab in which you can control the merging process.

Overview (top left in merge tab)

On the left side, you see an overview over the different input models and the output model (leftmost). The elements aligned to each other, and each element of the output model corresponds to individual or aligned elements from the input models. Initially, the elements are aligned automatically according to a heuristics that compares their annotations. You can change this alignment whenever you want (see below).

Solving conflicts between individual elements (on the right in merge tab)

After selecting one of the output elements in the overview, you will see a more detailed description of this element on the right. If the output element is supposed to replace several input elements (possibly with different properties), you will have to choose the properties of the output element. Conflicts are highlighted.

Merging the models (bottom left in merge tab)

After all conflicts have been resolved, you can press the "Merge" button (bottom left). Then the merging process is finished and the output model in its current form will be added to the model list in the main menu.

back to top

Building a new model

The build function of semanticSBML allows the user to construct a structural SBML file containing a number of biochemical reactions. The input is a list of KEGG reaction identifiers (e.g. R00127) or reaction strings (e.g. ATP + AMP -> 2 ATP).

To build a new SBML model from a list of biochemical reactions, click on the "Build model" tab in the main menu. In the tab, you can set a name for the model (which will be used as model name within the SBML model) and type or paste a list of chemical reactions into an input field. After pressing the "Next" button, you can specify the compartment for every reaction. After pressing the "Create Model" button, you can specify the model filename, and the model will be added to the model list in the main menu. The reactions and species in the model will carry MIRIAM annotations. For every reaction, an enzyme (without annotation) is included in the model.

Automatic annotation

The software will automatically annotate the constructed model. If the input is provided by KEGG reaction identifiers, all reactions and species will carry KEGG annotations. For the reaction string input, the software will try to recognize correct annotations for the different reactions and species. This is done by exact string matching of the input species to known metabolite names and regular expressions describing different database identifiers. For example, the three species in the reaction string C00002 + H2O -> ADP will be automatically annotated with the corresponding KEGG compound identifiers.

Working easily with semanticSBML

  1. There are keyboard shortcuts for some of the functions in the graphical user interface. They are indicated by underscored letters on the buttons.
  2. In the model list, you can automatically sort the models by clicking on the list headers.

Troubleshooting

We greatly appreciate your feedback. If you encounter any problems with semanticsSBML or if you have ideas how to improve the program or these instructions, please send us an email.

back to top

Exercises

    1. Build a model of the threonine pathway from the KEGG reaction IDs R00480, R02291, R01775, R01771, R01466 (two versions, with and without enzyme species)
    2. Annotate the model with the following IDs: (i) NCBI taxonomy ID 83333 for Escherichia coli ("model:is" qualifier); (ii) NCBI PubMed ID 11368770 for the article Chassagnole C, Fell DA, Rais B, Kudla B, Mazat JP. Control of the threonine-synthesis pathway in Escherichia coli: a theoretical and experimental approach. Biochem J. 2001 356(Pt 2):433-44. ("isDescribedBy" qualifier); (iii) KEGG pathway ID map00260 ("isVersionOf" qualifier).
    3. Display the model structure, check the model for correctness, and have a look at the element annotations.
    4. Save the model to disk
    5. Download the original threonine pathway model from Biomodels.net (BIOMD0000000066.xml) and compare it to your model (display the structures and find differences).
    1. Create an SBML model from the reactions "G6P <=> F6P" and "F6P + ATP <=> FBP + ADP". Choose "cell" as the compartment.
    2. Annotate all substances model with MIRIAM annotations pointing to the CHEBI database. G6P: Glucose-6-phosphate; F6P: Fructose-6-phosphate; FBP: Fructose-1,6-bisphosphate; ATP: Adenosine triphosphate; ADP: Adenosine diphosphate
    3. Annotate the compartment with the SBO term for "physical compartment"
    4. Display the model and check it for correctness.
    5. Look up the KEGG reaction ID for the second reaction and build a second model "model_2" from this reaction, in the compartment "Cell" (with capital C).
    6. Merge the two models "model_1" and "model_2". Make sure that the two compartments "cell" and "Cell" are merged to a single compartment.
    7. Save the merged model to disk