This section summarizes how to read and write SBML content using the facilities provided by libSBML's MATLAB interface.
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.
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.
TranslateSBML
accepts up to three possible arguments. They are, in order, as follows:
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.)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.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 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:
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.
The function OutputSBML
is the converse of TranslateSBML:
it writes an MATLAB_SBML structure to an XML file. It accepts two arguments:
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.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.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.
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 >>
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)
returns true (1
) or false (0
), depending on whether the model supplied as argument matches the expected form of a MATLAB_SBML structure. (OutputSBML
uses this function to determine whether it can proceed with writing out a given structure.)isoctave()
returns true (1
) or false (0
), depending on whether the run-time environment is Octave or MATLAB.