mass.io.sbml

SBML import and export using the python-libsbml package.

  • The SBML importer supports all versions of SBML that are compatible with the roadrunner package.

  • The sbml module supports the latest version of python-libsbml that is compatible with the roadrunner package.

  • The SBML importer supports the ‘fbc’ and ‘groups’ package extension.

  • The SBML exporter writes SBML Level 3 models.

  • Annotation information is stored on the mass objects.

  • Information from the ‘groups’ package is read.

  • All equations are written via MathML.

Parsing of models using the fbc extension was implemented as efficiently as possible, whereas (discouraged) fallback solutions are not optimized for efficiency. Futhermore, because the SBML kinetic law is used for the reaction kinetic laws, fbc information will NOT be written into or read from the SBML kinetic laws. Whether the fbc package extension is disabled or enabled will not change this behavior with kinetic laws.

Notes are only supported in a minimal way relevant for kinetic models, i.e. structured information from notes in the form:

"<p>key: value</p>"

Notes are read into the notes attribute of mass objects when reading SBML files. On writing, the notes attribute of mass objects dictionary is serialized to the SBML notes information.

Attribute information for EnzymeModuleForms and EnzymeModuleReactions are written into the SBML object notes field. Upon import of the SBML, the information is read into the enzyme specific attribute as long as the "key" in the notes matches the attribute name precisely.

The information specific to attributes of the EnzymeModule and EnzymeModuleDict information is stored using the groups extension by creating an SBML ‘group’ representing the enzyme module containing additional SBML group objects for enzyme module ligands, forms, and reactions for the categories of the enzyme module categorized dictionary attributes. The remaining information is written to the the notes field of the main SBML group for the enzyme module. Disabling use of the ‘groups’ package extension will result in the loss of the enzyme specific information, but it will not prevent EnzymeModuleForms and EnzymeModuleReactions from being written to the SBML model as species and reactions, respectively.

Annotations are read and written via annotation attribute for mass objects.

Some SBML related issues are still open, please refer to the respective issue:

Module Contents

Functions

read_sbml_model(filename[, f_replace])

Read SBML model from the given filename into a mass model.

write_sbml_model(mass_model, filename[, f_replace])

Write mass model to filename in SBML format.

validate_sbml_model(filename[, check_model, ...])

Validate the SBML model and returns the model along with the errors.

validate_sbml_model_export(mass_model, filename[, ...])

Validate export of a mass model to SBML, returning any errors.

Attributes

LOGGER

Logger for the sbml submodule.

SBML_LEVEL_VERSION

Current level and version supported for SBML export.

FBC_VERSION

Current version of the SBML 'fbc' package extension.

GROUPS_VERSION

Current version of the SBML 'groups' package extension.

CHAR_RE

Regex for ASCII character removal.

MASS_MOIETY_RE

Regex for mass moiety replacements.

SBML_MOIETY_RE

Regex for SBML moiety replacements.

RATE_CONSTANT_RE

Regex for recognizing and rate constants.

SBO_MODELING_FRAMEWORK

SBO term for the modeling framework

COBRA_FLUX_UNIT

Unit definition for cobra flux units.

NUMBER_ID_PREFIX

String to use as a prefix for identifiers starting with a number.

F_GENE

Key in F_REPLACE for the gene prefix clipping function.

F_GENE_REV

Key in F_REPLACE for the gene prefix adding function.

F_SPECIE

Key in F_REPLACE for the specie prefix clipping function.

F_SPECIE_REV

Key in F_REPLACE for the specie prefix adding function.

F_REACTION

Key in F_REPLACE for the reaction prefix clipping function.

F_REACTION_REV

Key in F_REPLACE for the reaction prefix adding function.

F_REPLACE

Contains functions for ID clipping/adding of prefixes.

ASCII_REPLACE

Contains ASCII characters and the value for their replacement.
mass.io.sbml.LOGGER[source]

Logger for the sbml submodule.

Type

logging.Logger

mass.io.sbml.SBML_LEVEL_VERSION = [3, 1][source]

Current level and version supported for SBML export.

Type

tuple

mass.io.sbml.FBC_VERSION = 2[source]

Current version of the SBML ‘fbc’ package extension.

Type

int

mass.io.sbml.GROUPS_VERSION = 1[source]

Current version of the SBML ‘groups’ package extension.

Type

int

mass.io.sbml.CHAR_RE[source]

Regex for ASCII character removal.

Type

re.Pattern

mass.io.sbml.MASS_MOIETY_RE[source]

Regex for mass moiety replacements.

Type

re.Pattern

mass.io.sbml.SBML_MOIETY_RE[source]

Regex for SBML moiety replacements.

Type

re.Pattern

mass.io.sbml.RATE_CONSTANT_RE[source]

Regex for recognizing and rate constants.

Type

re.Pattern

mass.io.sbml.SBO_MODELING_FRAMEWORK = SBO:0000062[source]

SBO term for the modeling framework

Type

str

mass.io.sbml.COBRA_FLUX_UNIT[source]

Unit definition for cobra flux units.

Type

UnitDefintion

mass.io.sbml.NUMBER_ID_PREFIX = _[source]

String to use as a prefix for identifiers starting with a number.

Type

str

mass.io.sbml.F_GENE = F_GENE[source]

Key in F_REPLACE for the gene prefix clipping function.

Type

str

mass.io.sbml.F_GENE_REV = F_GENE_REV[source]

Key in F_REPLACE for the gene prefix adding function.

Type

str

mass.io.sbml.F_SPECIE = F_SPECIE[source]

Key in F_REPLACE for the specie prefix clipping function.

Type

str

mass.io.sbml.F_SPECIE_REV = F_SPECIE_REV[source]

Key in F_REPLACE for the specie prefix adding function.

Type

str

mass.io.sbml.F_REACTION = F_REACTION[source]

Key in F_REPLACE for the reaction prefix clipping function.

Type

str

mass.io.sbml.F_REACTION_REV = F_REACTION_REV[source]

Key in F_REPLACE for the reaction prefix adding function.

Type

str

mass.io.sbml.F_REPLACE[source]

Contains functions for ID clipping/adding of prefixes.

Type

dict

mass.io.sbml.ASCII_REPLACE[source]

Contains ASCII characters and the value for their replacement.

Type

dict

mass.io.sbml.read_sbml_model(filename, f_replace=None, **kwargs)[source]

Read SBML model from the given filename into a mass model.

If the given filename ends with the suffix '.gz' (for example, 'myfile.xml.gz'), the file is assumed to be compressed in gzip format and will be automatically decompressed upon reading. Similarly, if the given filename ends with '.zip' or '.bz2', the file is assumed to be compressed in zip or bzip2 format (respectively).

Files whose names lack these suffixes will be read uncompressed. Note that if the file is in zip format but the archive contains more than one file, only the first file in the archive will be read and the rest are ignored.

To read a gzip/zip file, libSBML needs to be configured and linked with the zlib library at compile time. It also needs to be linked with the bz2 library to read files in bzip2 format. (Both of these are the default configurations for libSBML.)

This function supports SBML with FBC-v1 and FBC-v2. FBC-v1 models are converted to FBC-v2 models before reading.

The parser tries to fall back to information in notes dictionaries if information is not available in the FBC packages, e.g., CHARGE, FORMULA on species, or GENE_ASSOCIATION, SUBSYSTEM on reactions.

Notes

  • Provided file handles cannot be opened in binary mode, i.e., use:

    with open(path, "r" as f):
    read_sbml_model(f)

  • File handles to compressed files are not supported yet.

Parameters

  • filename (path to SBML file, SBML string, or SBML file handle) – SBML which is read into a mass model.

  • f_replace (dict) –

    Dictionary of replacement functions for gene, specie, and reaction. By default the following id changes are performed on import: clip 'G_' from genes, clip 'M_' from species, clip 'R_' from reactions.

    If no replacements should be performed, set f_replace={}.

  • **kwargs –

    number :

    In which data type should the stoichiometry be parsed. Can be float or int.

    Default is float.

    set_missing_bounds :

    bool indicating whether to set missing bounds to the default bounds from the MassConfiguration.

    Default is True.

    remove_char :

    bool indicating whether to remove ASCII characters from IDs.

    Default is True.

    stop_on_conversion_failbool

    bool indicating whether to stop trying to load the model if a conversion process fails. If False, then the loading of the model will be attempted anyways, despite a potential loss of information.

    Default is True.

Returns

The generated mass model.

Return type

MassModel or EnzymeModule

Raises

MassSBMLError – Errors due to :mass model specific requirements.

mass.io.sbml.write_sbml_model(mass_model, filename, f_replace=None, **kwargs)[source]

Write mass model to filename in SBML format.

The created model is SBML level 3 version 1 core (L3V1) using packages ‘fbc-v2’ and ‘groups-v1’ for optimal exporting. Not including these packages may result in some information loss when exporting the model.

If the given filename ends with the suffix '.gz' (for example, 'myfile.xml.gz'), libSBML assumes the caller wants the file to be written compressed in gzip format. Similarly, if the given filename ends with '.zip' or '.bz2', libSBML assumes the caller wants the file to be compressed in zip or bzip2 format (respectively). Files whose names lack these suffixes will be written uncompressed.

Special considerations for the zip format: If the given filename ends with '.zip', the file placed in the zip archive will have the suffix ".xml" or ".sbml". For example, the file in the zip archive will be named "test.xml" if the given filename is "test.xml.zip" or "test.zip". Similarly, the filename in the archive will be "test.sbml" if the given filename is "test.sbml.zip".

Parameters

  • mass_model (MassModel or EnzymeModule) – The mass model to write to into an SBML compliant modle file.

  • filename (str) – Path to which the model should be written

  • f_replace (dict) –

    Dictionary of replacement functions for gene, specie, and reaction. By default the following id changes are performed on import: add 'G_' to genes, add 'M_' to species, add 'R_' to reactions.

    If no replacements should be performed,set f_replace={}.

  • **kwargs –

    use_fbc_package :

    bool indicating whether SBML ‘fbc’ package extension should be used.

    Default is True.

    use_groups_package :

    bool indicating whether SBML ‘groups’ package extension should be used.

    Default is True.

    units :

    bool indicating whether units should be written into the SBMLDocument.

    Default is True.

    local_parameters :

    bool indicating whether reaction kinetic parameters should be written as local parameters of the kinetic law (default), or as global model parameters in the SBML model file.

    Default is True to write parameters as local parameters.

    write_objective :

    bool indicating whether the model objective(s) should also be written into the SBML model file.

    Default is False.

Raises

MassSBMLError – Errors due to :mass model specific requirements.

Warning

  • Setting the use_fbc_package=False may result in some information loss when writing the model.

  • Setting the use_groups_package=False may result in some information loss when writing the model. Information lost will include some attributes associated with enzyme modules and will likely result in an exported EnzymeModule becoming a MassModel upon reloading the model.

mass.io.sbml.validate_sbml_model(filename, check_model=True, internal_consistency=True, check_units_consistency=False, check_modeling_practice=False, **kwargs)[source]

Validate the SBML model and returns the model along with the errors.

kwargs are passed to read_sbml_model().

Parameters

  • filename (str) – The filename (or SBML string) of the SBML model to be validated.

  • check_model (bool) – Check some basic model properties. Default is True.

  • internal_consistency (bool) – Check internal consistency. Default is True.

  • check_units_consistency (bool) – Check consistency of units. Default is False.

  • check_modeling_practice (bool) – Check modeling practice. Default is False.

  • **kwargs –

    number :

    In which data type should the stoichiometry be parsed. Can be float or int.

    Default is float.

    set_missing_bounds :

    bool indicating whether to set missing bounds to the default bounds from the MassConfiguration.

    Default is True.

    remove_char :

    bool indicating whether to remove ASCII characters from IDs.

    Default is True.

    stop_on_conversion_failbool

    bool indicating whether to stop trying to load the model if a conversion process fails. If False, then the loading of the model will be attempted anyways, despite a potential loss of information.

    Default is True.

Returns

  • tuple (model, errors)

  • model (MassModel or EnzymeModule, or None) – The mass model if the file could be read successfully. If the file was not successfully read, None will be returned.

  • errors (dict) – Warnings and errors grouped by their respective types.

mass.io.sbml.validate_sbml_model_export(mass_model, filename, f_replace=None, **kwargs)[source]

Validate export of a mass model to SBML, returning any errors.

If no SBML errors or MASS fatal errors occur, the model will be written to the 'filename'.

kwargs are passed to either write_sbml_model() or validate_sbml_model().

Parameters

  • mass_model (MassModel or EnzymeModule) – The mass model to write to into an SBML compliant modle file.

  • filename (str) – Path to which the model should be written

  • f_replace (dict) –

    Dictionary of replacement functions for gene, specie, and reaction. By default the following id changes are performed on import: add 'G_' to genes, add 'M_' to species, add 'R_' to reactions.

    If no replacements should be performed,set f_replace={}.

  • **kwargs –

    use_fbc_package :

    bool indicating whether SBML ‘fbc’ package extension should be used.

    Default is True.

    use_groups_package :

    bool indicating whether SBML ‘groups’ package extension should be used.

    Default is True.

    units :

    bool indicating whether units should be written into the SBMLDocument.

    Default is True.

    local_parameters :

    bool indicating whether reaction kinetic parameters should be written as local parameters of the kinetic law (default), or as global model parameters in the SBML model file.

    Default is True to write parameters as local parameters.

    write_objective :

    bool indicating whether the model objective(s) should also be written into the SBML model file.

    Default is False.

    check_modelbool

    bool indicating whether to check some basic model properties.

    Default is True.

    internal_consistencybool

    bool indicating whether to check internal consistency.

    Default is True.

    check_units_consistencybool

    bool indicating whether to check consistency of units.

    Default is False.

    check_modeling_practicebool

    bool indicating whether to check modeling practice.

    Default is False.

    number :

    In which data type should the stoichiometry be parsed. Can be float or int.

    Default is float.

    set_missing_bounds :

    bool indicating whether to set missing bounds to the default bounds from the MassConfiguration.

    Default is True.

    remove_char :

    bool indicating whether to remove ASCII characters from IDs.

    Default is True.

    stop_on_conversion_failbool

    bool indicating whether to stop trying to load the model if a conversion process fails. If False, then the loading of the model will be attempted anyways, despite a potential loss of information.

    Default is True.

Returns

  • tuple (success, errors)

  • success (bool) – bool indicating whether the model was successfully exported to 'filename'.

  • errors (dict) – Warnings and errors grouped by their respective types.