4.1.1.3. wc_lang.sbml package

4.1.1.3.1. Submodules

4.1.1.3.2. wc_lang.sbml.io module

Encoding/decoding wc_lang models to/from SBML and reading/writing SBML-encoded models to/from XML files, one per submodel.

This enables WC-Lang-encoded models to be “round-tripped” with this sequence of operations:

  1. Model is transformed to remove metadata that can’t be exported to SBML

  2. Model is split into multiple models, each with one submodel

  3. Each model with one submodel is exported to SBML

  4. Each model with one submodel is imported from SBML

  5. Models with individual submodels are merged into a single model

WC-Lang models are exported to SBML with the following class mapping:

In addition, WC-Lang attributes which have no equivalent SBML attribute are mapped to SBase.annotation.

Note, that because WC-Lang and SBML have different semantics, some of aspects of WC-Lang cannot be mapped to SBML and vice-versa.

Author

Jonathan Karr <karr@mssm.edu>

Author

Arthur Goldberg <Arthur.Goldberg@mssm.edu>

Date

2019-03-21

Copyright

2017-2019, Karr Lab

License

MIT

class wc_lang.sbml.io.SbmlExporter[source]

Bases: object

Encode a wc_lang model with at most 1 submodel into SBML

classmethod run(model)[source]

Encode a wc_lang model with at most 1 submodel into SBML

  • Validate model

  • Create SBML document

  • Create SBML model

  • Encode model objects in SBML and add to SBML model in dependent order

Parameters

model (wc_lang.core.Model) – wc_lang model with at most 1 submodel

Returns

SBML document with SBML-encoded model

Return type

libsbml.SBMLDocument

Raises

ValueError – if the model cannot be exported to SBML because it contains multiple submodels

class wc_lang.sbml.io.SbmlImporter[source]

Bases: object

Import a wc_lang model from an SBML-encoded model

classmethod run(sbml_doc)[source]

Import a wc_lang model from an SBML-encoded model

Parameters

sbml_doc (libsbml.SBMLDocument) – SBML document with SBML-encoded model

Returns

wc_lang model

Return type

wc_lang.core.Model

class wc_lang.sbml.io.SbmlReader[source]

Bases: object

Read wc_lang models from SBML-encoded XML files, one for each submodel

run(dirname)[source]

Read wc_lang models from SBML-encoded XML files, one for each submodel

Parameters

dirname (str) – path to directory that contains SBML-encoded submodels of a model

Returns

wc_lang model

Return type

model (wc_lang.core.Model)

class wc_lang.sbml.io.SbmlWriter[source]

Bases: object

Write wc_lang models to collections of SBML-encoded XML files, one for each submodel

run(model, dirname)[source]

Write the submodels of a wc_lang model to separate SBML-encoded XML files.

Parameters

  • model (wc_lang.core.Model) – wc_lang model

  • dirname (str) – path to directory to save SBML-encoded XML files for each submodel

Raises

ValueError – if the model could not be written to a SBML-encoded file

4.1.1.3.3. wc_lang.sbml.util module

Utilities for writing/reading a wc_lang model to/from SBML

  • Higher level functions for creating, getting, and setting SBML objects

  • Utilities for wrapping libSBML calls

Author

Jonathan Karr <karr@mssm.edu>

Author

Arthur Goldberg <Arthur.Goldberg@mssm.edu>

Date

2019-03-21

Copyright

2017-2019, Karr Lab

License

MIT

exception wc_lang.sbml.util.LibSbmlError[source]

Bases: Exception

Exception raised when libSBML returns an error

class wc_lang.sbml.util.LibSbmlInterface[source]

Bases: object

Methods for compactly using libSBML to create SBML objects.

The libSBML method calls provide narrow interfaces, typically exchanging one value per call, which creates verbose code. The methods below aggregate multiple libSBML method calls to enable more compact usage.

XML_NAMESPACE = 'https://www.wholecell.org/ns/wc_lang'[source]
classmethod call_libsbml(method, *args, returns_int=False, debug=False)[source]

Call a libSBML method and handle any errors.

Unfortunately, libSBML methods that do not return data usually report errors via return codes, instead of exceptions, and the generic return codes contain virtually no information. This function wraps these methods and raises useful exceptions when errors occur.

Set returns_int True to avoid raising false exceptions or warnings from methods that return integer values.

Parameters

  • method (type, types.FunctionType, or types.MethodType) – libsbml method to execute

  • args (list) – a list of arguments to the libsbml method

  • returns_int (bool, optional) – whether the method returns an integer; if returns_int is True, then an exception will not be raised if the method call returns an integer

  • debug (bool, optional) – whether to print debug output

Returns

if the call does not return an error, return the libsbml

method’s return value, either an object that has been created or retrieved, or an integer value, or the libsbml success return code, libsbml.LIBSBML_OPERATION_SUCCESS

Return type

obj or int

Raises

LibSbmlError – if the libsbml call raises an exception, or returns None, or returns a known integer error code != libsbml.LIBSBML_OPERATION_SUCCESS

classmethod create_base_unit(unit_def_id, unit_def, kind, exponent=1, scale=0, multiplier=1.0)[source]

Add a unit to a SBML unit definition

Each SBML unit has four attributes:

  • kind

  • exponent

  • scale

  • multiplier

Parameters

  • unit_def_id (str) – id of SBML unit definition

  • unit_def (libsbml.UnitDefinition) – SBML unit definition

  • kind (str) – unit kind

  • exponent (int, optional) – exponent of the unit

  • scale (int, optional) – scale of the unit

  • multiplier (float, optional) – multiplier of the unit

Returns

SBML unit

Return type

libsbml.Unit

classmethod create_doc(level=3, version=2, packages=None)[source]

Create an SBMLDocument that, optionally, uses package(s).

Parameters

  • level (int, optional) – SBML level number

  • version (int, optional) – SBML version number

  • packages (dict that maps str to int, optional) – dictionary of required packages that maps package identifiers to package numbers

Returns

SBML document

Return type

libsbml.SBMLDocument

classmethod create_model(sbml_doc)[source]

Create a SBML model

Parameters

sbml_doc (libsbml.SBMLDocument) – SBML document

Returns

SBML model

Return type

libsbml.Model

classmethod create_parameter(sbml_model, id, value, units, name=None, constant=True)[source]

Add a parameter to an SBML model.

Parameters

  • sbml_model (libsbml.Model) – SBML model

  • id (str) – id

  • value (obj) – value

  • units (unit_registry.Unit) – units

  • name (str, optional) – name

  • constant (str, optional) – whether the parameter is a constant

Returns

SBML parameter

Return type

libsbml.Parameter

classmethod create_unit(unit, sbml_model)[source]

Add a unit definition to a SBML model

Parameters

  • unit (unit_registry.Unit) – unit

  • sbml_model (libsbml.Model) – SBML model that encodes the model

Returns

unit definition

Return type

libsbml.UnitDefinition

classmethod create_units(model, sbml_model)[source]

Set time, extent, and substance units of SBML model

Parameters

  • model (wc_lang.core.Model) – model

  • sbml_model (libsbml.Model) – SBML model that encodes the model

Returns

dictionary that maps units to ids of SBML unit definitions

Return type

dict

classmethod gen_annotations(model_obj, nested_attr_paths, sbml_obj)[source]

Export annotations from a model object to an SBML object

Parameters

  • model_obj (obj_tables.Model) – model object

  • nested_attr_paths (dict) – dictionary that maps names of attributes to paths to the attributes

  • sbml_obj (libsbml.SBase) – SBML object

Returns

string representation of the XML annotations of the model

Return type

str

classmethod gen_authors_annotation(model)[source]

Generate an annotation of the authors of a model

Parameters

model (wc_lang.core.Model) – model

Returns

string representation of the XML annotation of the authors of a model

Return type

str

static gen_nested_attr_paths(dotted_attr_paths)[source]

Generate structure representations of a list of nested attribute paths

Parameters

dotted_attr_paths (list of str) – List of paths to nested attributes. Each path is a dot-separated string of the series of nested attributes.

Returns

dictionary that ma

Return type

dict

classmethod gen_unit_id(unit)[source]

Generate an SBML unit id for a unit

Parameters

unit (unit_registry.Unit) – unit

Returns

SBML id for unit

Return type

str

Raises

ValueError – if an SBML id cannot be generated for the unit

classmethod get_annotations(model_obj, nested_attr_paths, sbml_obj, model_objs=None)[source]

Import annotations from a model object to an SBML object

Parameters

  • model_obj (obj_tables.Model) – model object

  • nested_attr_paths (dict) – dictionary that maps names of attributes to paths to the attributes

  • sbml_obj (libsbml.SBase) – SBML object

  • model_objs (dict, optional) – dictionary that maps classes of model objects to dictonaries that map ids of model objects to model objects

classmethod get_authors_annotation(model, sbml_model, model_objs)[source]

Import the SBML annotation of the authors of a model to a model

Parameters

  • model (wc_lang.core.Model) – model

  • sbml_model (libsbml.Model) – SBML model

  • model_objs (dict, optional) – dictionary that maps classes of model objects to dictonaries that map ids of model objects to model objects

classmethod get_commments(model_obj, sbml_obj)[source]

Import comments from an SBML object to a model object

Parameters

  • model_obj (obj_tables.Model) – model object

  • sbml_obj (libsbml.SBase) – SBML object

classmethod get_errors_warnings(sbml_doc)[source]

Get libSBML errors and warnings

Parameters

sbml_doc (libsbml.SBMLDocument) – SBML document

Returns

error messages list of str: warning messages list of str: log error messages list of str: log warning messages

Return type

list of str

classmethod get_math(get_math_func, Expression, model_objs, units_transform=None)[source]

Get the math of an SBML object

Parameters

  • get_math_func (callable) – function to get the math of an SBML object

  • Expression (type) – type of expression

  • model_objs (dict, optional) – dictionary that maps classes of model objects to dictonaries that map ids of model objects to model objects

Returns

expression

Return type

obj_tables.math.expression.Expression

classmethod get_unit(sbml_get_unit_func)[source]

Get units from SBML unit definition id

Parameters

sbml_get_unit_func (callable) – function to get the units of an SBML object

Returns

units

Return type

unit_registry.Unit

classmethod init_model(model, sbml_doc, packages=None)[source]

Create and initialize an SMBL model.

Parameters

  • model (wc_lang.core.Model) – model

  • sbml_doc (libsbml.SBMLDocument) – a libsbml SBMLDocument

  • packages (dict that maps str to int, optional) – dictionary of required packages that maps package identifiers to package numbers

Returns

the SBML model

Return type

libsbml.Model

classmethod normalize_unit_kind(kind, to_sbml_base_units=True)[source]

Normalize unit kind for SBML

Parameters

  • kind (str) – unit kind

  • to_sbml_base_units (bool, optional) – if True, map to fundamental SBML units

Returns

normalized unit kind

Return type

str

classmethod parse_annotations(sbml_obj)[source]

Import annotations from a model object to an SBML object

Parameters

sbml_obj (libsbml.SBase) – SBML object

Returns

dictionary of names and values of annotated attributes

Return type

dict

classmethod parse_parameter(sbml_parameter)[source]

Parse a parameter from an SBML parameter.

Parameters

sbml_parameter (libsbml.Parameter) – SBML parameter

Returns

id str: name float: value unit_registry.Unit: units

Return type

str

classmethod parse_unit_id(sbml_unit_def_id)[source]

Parse a unit from an SBML unit definition.

Parameters

sbml_unit_def_id (str) – id of SBML unit definition

Returns

units

Return type

unit_registry.Unit

classmethod parse_units(sbml_model)[source]

Parse SBML units to Python

Parameters

sbml_model (libsbml.Model) – SBML model

Returns

dictionary that maps ids of unit definitions to instance of unit_registry.Unit

Return type

dict

Raises

LibSbmlError – if units are not set or are inconsistent

classmethod raise_if_error(sbml_doc, message)[source]

Raise an error, if an SBML object has errors

Parameters

  • sbml_doc (libsbml.SBMLDocument) – SBML document

  • message (str) – summary of error

Raises

LibSbmlError – if the SBML object has errors

classmethod set_annotations(model_obj, nested_attr_paths, sbml_obj)[source]

Export annotations from a model object to an SBML object

Parameters

  • model_obj (obj_tables.Model) – model object

  • nested_attr_paths (dict) – dictionary that maps names of attributes to paths to the attributes

  • sbml_obj (libsbml.SBase) – SBML object

classmethod set_commments(model_obj, sbml_obj)[source]

Export comments from a model object to an SBML object

Parameters

  • model_obj (obj_tables.Model) – model object

  • sbml_obj (libsbml.SBase) – SBML object

classmethod set_math(set_math_func, expression, units_transform=None)[source]

Set the math of an SBML object

Parameters

  • set_math_func (callable) – function to set the math of an SBML object

  • expression (obj_tables.math.expression.Expression) – expression

classmethod set_unit(sbml_set_unit_func, unit)[source]

Set the units of an SBML object

Parameters

  • sbml_set_unit_func (callable) – function to set the units of an SBML object

  • unit (unit_registry.Unit) – unit

classmethod str_from_xml_node(xml_node)[source]

Convert an XML string (e.g., from a Note in an SBML document) to a Python string.

Parameters

xml_node (libsbml.XMLNode) – an XML string that can be stored as a Note in an SBML document

Returns

a string

Return type

str

classmethod str_to_xml_node(str)[source]

Convert a Python string to an XML string that can be stored as a Note in an SBML document.

Parameters

str (str) – a string

Returns

an XML string that can be stored as a Note in an SBML document

Return type

libsbml.XMLNode

classmethod verify_doc(sbml_doc, level=3, version=2, strict_units=True)[source]

Verify that an SBML document is valid, and raise an exception if the document is not valid

  • SBML-compatible

  • Valid SBML

  • Consistent

Parameters

  • sbml_doc (libsbml.SBMLDocument) – SBML document

  • level (int, optional) – SBML level number

  • version (int, optional) – SBML version number

  • strict_units (bool, optional) – if True, strictly verify that the units are consistent

classmethod verify_doc_is_compatible(sbml_doc, level=3, version=2)[source]

Check the compatibility of an SBML document with a specific level and version, and raise an exception if the document is not verify_doc_is_compatible

Parameters

  • sbml_doc (libsbml.SBMLDocument) – SBML document

  • level (int, optional) – SBML level number

  • version (int, optional) – SBML version number

classmethod verify_doc_is_consistent(sbml_doc, strict_units=True)[source]

Check that an SBML document is consistent, and raise an exception if the document is not consistent

Parameters

  • sbml_doc (libsbml.SBMLDocument) – SBML document

  • strict_units (bool, optional) – if True, strictly verify that the units are consistent

classmethod verify_doc_is_valid_sbml(sbml_doc)[source]

Check that an SBML document is valid, and raise an exception if the document is not valid

Parameters

sbml_doc (libsbml.SBMLDocument) – SBML document

class wc_lang.sbml.util.SbmlAssignmentRuleMixin[source]

Bases: wc_lang.sbml.util.SbmlModelMixin

Methods for exporting/import expression models to/from SBML

export_relations_to_sbml(sbml_model, sbml)[source]

Add relationships to/from object to SBML object.

Parameters

  • sbml_model (libsbml.Model) – SBML model

  • sbml (libsbml.SBase) – SBML object

export_to_sbml(sbml_model)[source]

Add expression to a SBML model.

Parameters

sbml_model (libsbml.Model) – SBML model

Returns

SBML assignment rule

Return type

libsbml.AssignmentRule

import_from_sbml(sbml)[source]

Load expression from SBML assignment rule

Parameters

sbml (libsbml.AssignmentRule) – SBML assignment rule

import_relations_from_sbml(sbml, objs)[source]

Load relationships to/from expression from SBML assignment rule

Parameters

  • sbml (libsbml.AssignmentRule) – SBML assignment rule

  • objs (dict) – dictionary that maps WC-Lang types to dictionaries that map the ids of WC-Lang objects to WC-Lang objects

class wc_lang.sbml.util.SbmlModelMixin[source]

Bases: object

Methods for exporting/import models to/from SBML

export_relations_to_sbml(sbml_model, sbml)[source]

Add relationships to/from object to SBML object.

Parameters

  • sbml_model (libsbml.Model) – SBML model

  • sbml (libsbml.SBase) – SBML object

export_to_sbml(sbml_model)[source]

Add object to SBML model.

Parameters

sbml_model (libsbml.Model) – SBML model

Returns

SBML object

Return type

libsbml.SBase

gen_sbml_id()[source]

Generate SBML id from id

Returns

SBML id

Return type

str

import_from_sbml(sbml)[source]

Load object from SBML object

Parameters

sbml (libsbml.SBase) – SBML object

import_relations_from_sbml(sbml, objs)[source]

Load relations to/from object from SBML object

Parameters

  • sbml (libsbml.SBase) – SBML object

  • objs (dict) – dictionary that maps WC-Lang types to dictionaries that map the ids of WC-Lang objects to WC-Lang objects

classmethod parse_sbml_id(sbml_id)[source]

Parse id from SBML id

Parameters

sbml_id (str) – SBML id

Returns

id

Return type

str

4.1.1.3.4. Module contents