Command Line Scripts

Two very basic command line scripts can support conversion between SBML coded models and the tabular format.

Supported spreadsheet formats are MS Excel (*.xlsx) and OpenOffice (*.ods). These spreadsheet documents contain sheets for SBML components. Comma-separated-value files (*.csv) are supported as well, one file for each SBML component.

In case you are not a Python programmer, ask a colleague to set up Python 3 on your system, install sbmlxdf, create the two Python scripts given below and show you how these command line scripts can be used.

Note

Only sheets / csv-files for SBML components used in your model design are required. Same holds for column names in tables.

Names of sheets / csv-file are significant. Your spreadsheet may contain additional sheets not recognized by smblxdf. Such sheets may be of help when creating/modifying models.

Tip

Use version control when modifying models. Once your model has passed validation, generate the SBML file and commit the SBML file to your repository.

SBML -> Excel

This command line script takes as input an SMBL model and converts it to the corresponding spreadsheet document.

This could be your first step in creating a spreadsheet template from an existing SBML model.

Example (assuming the SBML model other_model.xml in directory ./SBML_models):

$ python3 sbml2xlsx.py SBML_models/other_model.xml
spreadsheet created: SBML_models/other_model.xlsx

Python code for script sbml2xlsx.py:

# sbml2xlsx.py
import sys
import os.path
import sbmlxdf

# basic command line argument handling
if len(sys.argv) == 2:
    sbml_in = sys.argv[1]
    xlsx_out = sbml_in.replace('.xml', '.xlsx')
else:
    print('use:', os.path.basename(sys.argv[0]), 'sbml_file')
    sys.exit()

model = sbmlxdf.Model(sbml_in)
model.to_excel(xlsx_out)
print('spreadsheet created:', xlsx_out)

Excel -> SBML

This command line script takes as input a spreadsheet document and converts it to the corresponding SBML model.

It is a two-step process:

• First, the model is checked against SBML standards, using libsbml functionality. In case validation passes, the SBML model is created (2nd step).

• In case the validation fails, SBML warnings and/or errors messages are printed to the console. The SBML model is not created.

  It is your task to first correct the warnings/errors in your spreadsheet document and re-run the conversion script. Warning and error messages give an indication what needs to be corrected. Warning and error messages are stored in the text file ./results/tmp.txt. (Line numbers refer to xml file ./results/tmp.xml)

Note

While not recommended, you could run the script with the optional parameter -f to force creation of the SBML model despite warning messages. (Error messages require correction in any case.)

Example (assuming a spreadsheet document my_model.xlsx in directory ./SBML_models):

$ python3 xlsx2sbml.py SBML_models/my_model.xlsx
Validation result: {'Errors': 2}
Please correct spreadsheet and re-run converter

{'Errors': 2} NOK: not SBML compliant, see results file!
line 752: (21111 [Error]) The value of a <speciesReference> 'species'
attribute must be the identifier of an existing <species> in the model.
Reference: L3V2 Section 4.11.3
 The <speciesReference> in the <reaction> with id 'mr_t8'
 references species 'L', which is undefined.

line 778: (21111 [Error]) The value of a <speciesReference> 'species'
attribute must be the identifier of an existing <species> in the model.
Reference: L3V2 Section 4.11.3
 The <speciesReference> in the <reaction> with id 'mr_e9'
 references species 'L', which is undefined.

During validation two errors were detected. The SBML file is not created. The error messages indicate that species L is used in two reactions, however species L is not yet defined.

Add species L to your spreadsheet document (sheet species) and run the converter again.

$ python3 xlsx2sbml.py SBML_models/my_model.xlsx
Validation result: {}
SBML model created: SBML_models/my_model.xml

This time validation was successful and the SBML model was created.

Python code for script sbml2xlsx.py:

# xslx2sbml.py
import sys
import os.path
import sbmlxdf

# basic command line argument handling
if len(sys.argv) > 1:
   excel_in = sys.argv[1]
   sbml_out = excel_in.replace('.xlsx', '.xml')
else:
   print('use:', os.path.basename(sys.argv[0]), 'xlsx_file [-f]')
   print('     -f: forced; write SBML despite warnings')
   sys.exit()
forced = (len(sys.argv) > 2) and (sys.argv[2] == '-f')

# read in excel file
model = sbmlxdf.Model(excel_in)
# check compliance with SBML specification
val_result = model.validate_sbml('tmp.xml')
print('validation result:', val_result)
if ((len(val_result) == 0) or
   (forced and ('Errors' not in val_result.keys()))):
   model.export_sbml(sbml_out)
   print('SBML model created:', sbml_out)
else:
   print('correct spreadsheet and run converter again\n')
   print(open(os.path.join('.', 'results', 'tmp.txt'), 'r').read())