sbmlxdf 0.2.2

convert between SBML and tabular structures

Install:

$ pip install sbmlxdf

Convert between SBML coded files and pandas DataFrames

sbmlxdf supports, with few exceptions, all functionality of SBML L3V2 core package[^1] and extension packages Flux Balance Constraints (fbc)[^2], Groups (groups)[^3] and Distributions (distrib)[^4].

using libSBML API for accessing SBML[^5].

Note: python-libsbml-experimental package is used to support features in distrib package. It is imported with import libsbml. If python-libsbml package is installed subsequently, e.g. as requirement for another tool, some functionality might get lost. In such case python-libsbml-experimental should be re-installed using pip install.

Example:

import sbmlxdf

input_xml = 'SBML_Models/e_coli_core.xml'

model = sbmlxdf.Model()
if model.import_sbml(input_xml):
    print('SBML model imported:', input_xml)
    model.to_excel('model.xlsx')
    print('SBML model written to Excel: model.xlsx')
    model.to_csv('model')
    print('also SBML model written to .csv: ./model/*.csv')

    # read model from Excel spreadsheet
    outm = sbmlxdf.Model('model.xlsx')
    print('SBML model imported from model.xlsx')
    is_valid_sbml = outm.validate_sbml('checkModel.xml')
    print('SBML file valid:', is_valid_sbml)

    model_dfs = outm.to_df()
    print('model exported to dict of pandas dataframes')
    print(model_dfs.keys())

    df_r = model_dfs['reactions']
    print(len(df_r), 'reactions found, first reaction:' )
    print(df_r.iloc[0])
    print('reactants and products for some reactions:')
    for id, reaction in df_r.head().iterrows():
        print('reaction:', id)
        for record in sbmlxdf.extract_records(reaction['reactants']):
            print('  reactant: ', sbmlxdf.extract_params(record))
        for record in sbmlxdf.extract_records(reaction['products']):
            print('  product:  ', sbmlxdf.extract_params(record))

Methods

create Model object, empty or from file   sbmlxdf.Model()   sbmlxdf.Model('model.xml')   sbmlxdf.Model('model.xlsx')   sbmlxdf.Model('model.ods')   sbmlxdf.Model('model_dir')

read/write SBML file   sbmlxdf.Model.import_sbml('model.xml')   sbmlxdf.Model.export_sbml('model.xml')

read/write Excel spreadsheet with model data  sbmlxdf.Model.from_excel('model.xlsx')  sbmlxdf.Model.to_excel('model.xlsx')

read/write OpenOffice spreadsheet with model data  sbmlxdf.Model.from_excel('model.ods')  sbmlxdf.Model.to_excel('model.ods')

read/write model coded in set of .csv files   sbmlxdf.Model.from_csv('model_dir')   sbmlxdf.Model.to_csv('model_dir')

convert model data to/from dict of pandas dataframes   sbmlxdf.Model.to_df()   sbmlxdf.Model.from_df(model_dict)

validate compliance with SBML specification (units check enabled/disabled)   sbmlxdf.Model.validate_sbml('tmp.xml', units_check=True)

miscellanious - data extraction helper functions   sbmlxdf.misc.extract_params(record_str)     extract dict of parameters from record   sbmlxdf.misc.extract_records(lo_record_str)     extract record from a list of records   sbmlxdf.misc.extract_lo_records(lo_lo_records_str)     extract list of records from a list of list of records   sbmlxdf.misc.extract_xml_attrs(xml_annots, ns=None, token=None)     extract attributes from xml-annots str for given namespace and/or token

Workflow for creating SBML files:

1. Create and Excel model. e.g. 'my_model.xlsx'

   You may start with an Excel model template, which you modify/configure to your needs. Excel model templates can be created by converting existing SBML models to Excel, e.g. using models from *./test/data directory

   model = sbmlxdf.Model('ReferenceSBMLmodel.xml')

   model.to_excel('templateModel.xlsx')

2. Import Excel coded model

   my_model = sbmlxdf.Model('my_model.xlsx')

3. Validate compliance with SBML standard

   A compliance report *.txt will be created in the ./results directory, with detailed warning and error messages generated by libSBML validation. A corresponding *.xml document can be used to cross reference the line numbers.

   my_model.validate_sbml('tmp.xml')

4. Correct warnings/errors by updating your Excel coded model and go back to step 2.

5. Upon successful validation create your SBML coded model

   my_model.export_sbml('my_model.xml')

Sample Python script to generate SBML coded model from Excel coded model:

# 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 file created:', sbml_out)
else:
   print('correct xlsx and run converter again; -f option ignores warnings.\n')
   print(open(os.path.join('.', 'results', 'tmp.txt'), 'r').read())

Sample Python script to generate Excel coded model from SBML coded model:

# 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('xlsx file created:', xlsx_out)

Peter Schubert, October 2020

[^1]: The Systems Biology Markup Language (SBML): Language Specification for Level 3 Version 2 Core (Release 2) Authors: Michael Hucka, Frank T. Bergmann, Claudine Chaouiya, Andreas Dräger, Stefan Hoops, Sarah M. Keating, Matthias König, Nicolas Le Novère, Chris J. Myers, Brett G. Olivier, Sven Sahle, James C. Schaff, Rahuman Sheriff, Lucian P. Smith, Dagmar Waltemath, Darren J. Wilkinson, and Fengkai Zhang

[^2]: Olivier, B. G., & Bergmann, F. T. (2018). SBML Level 3 Package: Flux Balance Constraints version 2. Journal of Integrative Bioinformatics, 15(1), 20170082.

[^3]: Hucka, M., & Smith, L. P. (2016). SBML Level 3 package: Groups, Version 1 Release 1. _Journal of Integrative Bioinformatics, 13(3), 290.

[^4]: Smith, L. P., Moodie, S. L., Bergmann, F. T., Gillespie, C., Keating, S. M., König, M., Myers, C. J., Swat, M. J., Wilkinson, D. J., and Hucka, M. (2020). The Distributions Package for SBML Level 3. Retrieved from from COMBINE, https://identifiers.org/combine.specifications/ sbml.level-3.version-1.distrib.version-1.release-1

[^5]: Bornstein, B. J., Keating, S. M., Jouraku, A., and Hucka M. (2008) LibSBML: An API Library for SBML. Bioinformatics, 24(6):880--881, doi:10.1093/bioinformatics/btn051.