This section summarizes how to read and write SBML content using the facilities provided by libSBML's MATLAB interface.

Getting started: the 1-minute introduction

The libSBML MATLAB interface centers around two functions: one called TranslateSBML that can read an SBML document and convert it to a structure within MATLAB, and another function called OutputSBML that can convert and write this kind of structure as an SBML document file. The following code examples shows how easy it is to use TranslateSBML to read in an SBML file:

>> model = TranslateSBML('test.xml')

model = 

              typecode: 'SBML_MODEL'
                metaid: ''
                 notes: [1x281 char]
            annotation: ''
            SBML_level: 2
          SBML_version: 1
                  name: ''
                    id: 'Branch'
    functionDefinition: [1x0 struct]
        unitDefinition: [1x0 struct]
           compartment: [1x1 struct]
               species: [1x4 struct]
             parameter: [1x0 struct]
                  rule: [1x0 struct]
              reaction: [1x3 struct]
                 event: [1x0 struct]
           time_symbol: ''
          delay_symbol: ''
            namespaces: [1x1 struct]

>>

If a filename is not supplied as an argument to TranslateSBML, then it will open a file browser window so that you can navigate and select a file to read. The TranslateSBML function accepts some additional arguments too, and can produce additional output values, as described below.

TranslateSBML

Throughout this documentation, we use the term the MATLAB_SBML structure to refer to the in-memory MATLAB data structure used by TranslateSBML and OutputSBML. As mentioned above, the job of TranslateSBML is to create this in-memory structure from an SBML file.

Input arguments

TranslateSBML accepts up to four possible arguments. They are, in order, as follows:

filename: This is the name of the file to be imported. If the file is not in the current directory, then the argument must be a full pathname (either absolute or relative to the current working directory). If MATLAB has been invoked noninteractively from the command line, the filename is a required argument.
validateFlag: This flag tells libSBML whether to perform full validation of the SBML file being read. The default value is 0, which signifies not to perform validation. (Note libSBML will still check for and report basic XML parsing errors regardless of the value of this flag.)
verboseFlag: A value of 1 (the default) indicates that TranslateSBML should perform the validation process interactively, displaying errors and prompting the user for feedback if the model is invalid. A value of 0 will suppress user interaction, and is useful when calling TranslateSBML from within another MATLAB function/script.
fbcGeneProductOptions: This optional argument is an array of two values that allows the user to change the behavior relating to geneProduct elements in the fbc package. The first value in the array impacts of the infix respresentation of a GeneProductAssociation. A value of [0, 1] (the default) indicates that TranslateSBML should interpret the geneProductAssociation using the label attribute to refer to the geneProduct. A value of [1,n] indicates the id attribute should be used. Note the second value in the array has no impact on TranslateSBML.

The following example illustrates the behavior of TranslateSBML when it is given the additional arguments for validation and verbosity:

>> model = TranslateSBML('test.xml', 1, 1)
The model contains 0 errors and 6 warnings.

Do you want to exclude the warnings from the list? Enter y/n n

************************************
Line ErrorId Severity Message
34: (99505)  Warning  In situations when a mathematical expression contains
literal numbers or parameters whose units have not been declared, it is not
possible to verify accurately the consistency of the units in the
expression.  The units of the <kineticLaw> <math> expression 'k1 * X0'
cannot be fully checked. Unit consistency reported as either no errors or
further unit errors related to this object may not be accurate.

54: (99505)  Warning  In situations when a mathematical expression contains
literal numbers or parameters whose units have not been declared, it is not
possible to verify accurately the consistency of the units in the
expression.  The units of the <kineticLaw> <math> expression 'k2 * S1'
cannot be fully checked. Unit consistency reported as either no errors or
further unit errors related to this object may not be accurate.

74: (99505)  Warning  In situations when a mathematical expression contains
literal numbers or parameters whose units have not been declared, it is not
possible to verify accurately the consistency of the units in the
expression.  The units of the <kineticLaw> <math> expression 'k3 * S1'
cannot be fully checked. Unit consistency reported as either no errors or
further unit errors related to this object may not be accurate.

43: (80701)  Warning  As a principle of best modeling practice, the units
of a <parameter> should be declared rather than be left undefined. Doing so
improves the ability of software to check the consistency of units and
helps make it easier to detect potential errors in models.

63: (80701)  Warning  As a principle of best modeling practice, the units
of a <parameter> should be declared rather than be left undefined. Doing so
improves the ability of software to check the consistency of units and
helps make it easier to detect potential errors in models.

83: (80701)  Warning  As a principle of best modeling practice, the units
of a <parameter> should be declared rather than be left undefined. Doing so
improves the ability of software to check the consistency of units and
helps make it easier to detect potential errors in models.


Do you want to load the model anyway? Enter y/n y

model = 

              typecode: 'SBML_MODEL'
                metaid: ''
                 notes: [1x281 char]
            annotation: ''
            SBML_level: 2
          SBML_version: 1
                  name: ''
                    id: 'Branch'
    functionDefinition: [1x0 struct]
        unitDefinition: [1x0 struct]
           compartment: [1x1 struct]
               species: [1x4 struct]
             parameter: [1x0 struct]
                  rule: [1x0 struct]
              reaction: [1x3 struct]
                 event: [1x0 struct]
           time_symbol: ''
          delay_symbol: ''
            namespaces: [1x1 struct]

>>

The following example illustrates the behavior of TranslateSBML when it is given the additional fbc argument:

>> m = TranslateSBML('fbc.xml', 0, 0, [0,1])

>> m.fbc_geneProduct(1).fbc_id = g_1

>> m.fbc_geneProduct(1).fbc_label = g1-hh

>> m.fbc_geneProduct(2).fbc_id = g_2

>> m.fbc_geneProduct(2).fbc_label = g2-23

>> m.reaction(2).fbc_geneProductAssociation(1).fbc_association

ans = 

           typecode: 'SBML_FBC_OR'
             metaid: 'ss'
              notes: ''
         annotation: ''
            cvterms: []
            sboTerm: -1
    fbc_association: '(g1-hh or g2-23)'
              level: 3
            version: 1
        fbc_version: 2


>> m2 = TranslateSBML('fbc.xml', 0, 0, [1,1])

>> m2.fbc_geneProduct(1).fbc_id = g_1

>> m2.fbc_geneProduct(1).fbc_label = g1-hh

>> m2.fbc_geneProduct(2).fbc_id = g_2

>> m2.fbc_geneProduct(2).fbc_label = g2-23

>> m2.reaction(2).fbc_geneProductAssociation(1).fbc_association

ans = 

           typecode: 'SBML_FBC_OR'
             metaid: 'ss'
              notes: ''
         annotation: ''
            cvterms: []
            sboTerm: -1
    fbc_association: '(g_1 or g_2)'
              level: 3
            version: 1
        fbc_version: 2

>>

Output values

The main output value from TranslateSBML is a MATLAB_SBML structure that captures the content of an SBML file in a form that can be manipulated within MATLAB. However, TranslateSBML can actually return multiple values. We describe them in the list below:

model: This is the MATLAB_SBML structure corresponding to the content of an SBML document.
errors: The output of validation performed by libSBML can be captured into a second value returned by TranslateSBML. The value is an array of structures detailing the warnings and errors encountered while reading and translating the SBML file. Capturing this output can be especially handy when calling the function from other MATLAB code.

The following illustrates how the output of the errors reported for the previous TranslateSBML example could be captured using the error output variable:

>> [model, errors] = TranslateSBML('test.xml', 1, 0)

model = 

              typecode: 'SBML_MODEL'
                metaid: ''
                 notes: [1x281 char]
            annotation: ''
            SBML_level: 2
          SBML_version: 1
                  name: ''
                    id: 'Branch'
    functionDefinition: [1x0 struct]
        unitDefinition: [1x0 struct]
           compartment: [1x1 struct]
               species: [1x4 struct]
             parameter: [1x0 struct]
                  rule: [1x0 struct]
              reaction: [1x3 struct]
                 event: [1x0 struct]
           time_symbol: ''
          delay_symbol: ''
            namespaces: [1x1 struct]


errors = 

1x6 struct array with fields:
    line
    errorId
    severity
    message

>> errors(1)

ans = 

        line: 34
     errorId: 99505
    severity: 'Warning '
     message: [1x405 char]

>> errors(1).message

ans =

In situations when a mathematical expression contains literal numbers or
parameters whose units have not been declared, it is not possible to verify
accurately the consistency of the units in the expression.  The units of
the <kineticLaw> <math> expression 'k1 * X0' cannot be fully checked. Unit
consistency reported as either no errors or further unit errors related to
this object may not be accurate.

>>

Each error structure returned by TranslateSBML contains four fields: a line number, indicating approximately where in the SBML file the error occurred; errorId, the libSBML error/warning identification code; severity, indicating how serious the issue is; and message, the text of the error or warning for the issue reported by libSBML.

version: This returns a structure that gives the version information for libSBML.

The following illustrates the structure:

>> [model, errors, version] = TranslateSBML('test.xml')

version = 

           libSBML_version: 51500
    libSBML_version_string: '5.15.0'
                XML_parser: 'libxml2'
        XML_parser_version: '2.7.8'
              isFBCEnabled: 'enabled'

>>

OutputSBML

The function OutputSBML is the converse of TranslateSBML: it writes an MATLAB_SBML structure to an XML file. It accepts five arguments:

model: This argument must be a MATLAB_SBML structure representing the model to be written out to a file. Note that the structure will not be validated to check if it is fully correct SBML; OutputSBML will only verify the basic integrity of the structure (i.e., to make sure it has the form expected of a MATLAB_SBML structure), but nothing more.

filename: An optional argument giving the name of the file where the SBML content should be written. If this argument is omitted, OutputSBML will open a file browser window (in environments that permit it) allowing you to indicate the location and name of the file to be written.

extensionsAllowed: An optional argument indicating that when determining whether the MATLAB_SBML structure represents a valid structure any additional fields are ignored. The default value is 1. If this argument is set to 0, a structure will be considered valid if it contains only the expected fields and no additional fields.

applyUserValidation: An optional argument indicating that when determining whether the MATLAB_SBML structure represents a valid structure user defined validation is applied. The default value is 0 which disables custom validation. A value of 1 indicates that when using the function isSBML_Model to assess whether the MATLAB_SBML structure is correct the applyUserValidation function should be invoked. This allows a user to add their own custom validation criteria to the export of SBML from MATLAB.

fbcGeneProductOptions: This optional argument is an array of two values that allows the user to change the behavior relating to geneProduct elements in the fbc package. The first value in the array impacts of the infix respresentation of a GeneProductAssociation. A value of [0, 1] (the default) indicates that OutputSBML should interpret the geneProductAssociation using the label attribute to refer to the geneProduct. A value of [1,n] indicates the id attribute should be used. The second entry in the array indicates whether OutputSBML should add geneProduct elements if it encounters a label/id in an association element that does not correspond to an existing geneProduct. A value of [0, 1] (the default) will add missing geneProducts. A value of [n, 0] turns off this behavior.

The MATLAB_SBML structure

As mentioned above, The MATLAB_SBML structure used by libSBML's MATLAB interface captures the content of an SBML file in a form that can be manipulated within MATLAB. The structure contains many fields, and many of these fields are arrays of other structures that correspond to SBML components. Indexing into the array allows the user to access specific model elements and attributes.

Additional functions are included with the interface to allow a user to query the expected fields of the MATLAB_SBML structure.

getStructureFieldnames(typecode, level, version, packageVersion(optional)) returns an array of the structure fieldnames for the specified SBML type and the given SBML level and version.
getValueTypes(typecode, level, version, packageVersion(optional)) returns an array of the data types of the fields in the structure for the specified SBML type and the given SBML level and version.
getDefaultValues(typecode, level, version, packageVersion(optional)) returns an array of the default values of the fields in the structure for the specified SBML type and the given SBML level and version.

The following is an example of accessing the first species in a model:

>> model.species(1)

ans = 

                     typecode: 'SBML_SPECIES'
                       metaid: ''
                        notes: ''
                   annotation: ''
                         name: ''
                           id: 'S1'
                  compartment: 'compartmentOne'
                initialAmount: NaN
         initialConcentration: 0
               substanceUnits: ''
             spatialSizeUnits: ''
        hasOnlySubstanceUnits: 0
            boundaryCondition: 0
                       charge: 0
                     constant: 0
           isSetInitialAmount: 0
    isSetInitialConcentration: 1
                  isSetCharge: 0

>>

The following is an example of using the query functions to establish the expected fieldnames, types and values:

>> getStructureFieldnames('compartment', 3, 1)

ans = 

  Columns 1 through 8

    'typecode'    'metaid'    'notes'    'annotation'    'cvterms'    'sboTerm'    'name'    'id'

  Columns 9 through 14

    'spatialDimensions'    'size'    'units'    'constant'    'isSetSize'    'isSetSpatialDime...'

>> getValueType('compartment', 3, 1)

ans = 

  Columns 1 through 8

    'SBML_COMPARTMENT'    'char'    'char'    'char'    'structure'    'int'    'char'    'char'

  Columns 9 through 14

    'double'    'double'    'char'    'bool'    'bool'    'bool'

>> getDefaultValues('compartment', 3, 1)

ans = 

  Columns 1 through 13

    'SBML_COMPARTMENT'    ''    ''    ''    []    [-1]    ''    ''    [NaN]    [NaN]    ''    [0]    [0]

  Column 14

    [0]

>>

Other functions provided by the libSBML MATLAB interface

LibSBML's MATLAB interface comes with a few other scripts that are called internally by TranslateSBML and OutputSBML, but may also be useful independently:

isSBML_Model(model, extensionsAllowed, applyUserValidation) returns true (1) or false (0), depending on whether the model supplied as argument matches the expected form of a MATLAB_SBML structure. The optional argument extensionsAllowed (default = 1) determines whether additional fields are ignored. A second optional argument applyUserValidation determines whether the additional script applyUserValidation is invoked from the isSBML_Model function. These argument is described in more detail in the text on OutputSBML above. (OutputSBML uses this function to determine whether it can proceed with writing out a given structure.)
applyUserValidation(SBMLStructure, level, version, packages, pkgVersion) is invoked from isSBML_Model and allows user to add custom validation to their export of SBML. The function included contains an example of how it might be used.
isoctave() returns true (1) or false (0), depending on whether the run-time environment is Octave or MATLAB.
iaEnables(package) returns true (1) or false (0), depending on whether the libSBML instance supports the package.