libSBML Python API  5.10.0
 All Classes Namespaces Files Functions Variables Modules Pages
libsbml.L3ParserSettings Class Reference
Inheritance diagram for libsbml.L3ParserSettings:
[legend]

Detailed Description

{core}

A helper class for controlling the behavior of the text-string formula parser.

This class of objects is defined by libSBML only and has no direct equivalent in terms of SBML components. This class is not prescribed by the SBML specifications, although it is used to implement features defined in SBML.

The function libsbml.parseL3FormulaWithSettings(), along with its variants libsbml.parseFormula() and libsbml.parseL3FormulaWithModel(), are the interfaces to a parser for mathematical formulas expressed as text strings. The parser converts the text-string formulas into Abstract Syntax Trees (ASTs), represented in libSBML using ASTNode objects. Compared to the parser implemented by the function libsbml.parseFormula(), which was designed primarily for converting the mathematical formula strings in SBML Level 1, the 'L3' variant of the parser accepts an extended formula syntax. It also has a number of configurable behaviors. This class (L3ParserSettings) is an object used to communicate the configuration settings with callers.

The following aspects of the parser are configurable:

  • The function log with a single argument ("<code>log(x)</code>") can be parsed as log10(x), ln(x), or treated as an error, as desired.
  • Unary minus signs can be collapsed or preserved; that is, sequential pairs of unary minuses (e.g., "<code>- -3</code>") can be removed from the input entirely and single unary minuses can be incorporated into the number node, or all minuses can be preserved in the AST node structure.
  • Parsing of units embedded in the input string can be turned on and off.
  • The string avogadro can be parsed as a MathML csymbol or as an identifier.
  • A Model object may optionally be provided to the parser using the variant function calllibsbml.SBML_parseL3FormulaWithModel(). or stored in a L3ParserSettings object passed to the variant function libsbml.parseL3FormulaWithSettings(). When a Model object is provided, identifiers (values of type SId) from that model are used in preference to pre-defined MathML definitions. More precisely, the Model entities whose identifiers will shadow identical symbols in the mathematical formula are: Species, Compartment, Parameter, Reaction, and SpeciesReference. For instance, if the parser is given a Model containing a Species with the identifier "<code>pi</code>", and the formula to be parsed is "<code>3*pi</code>", the MathML produced will contain the construct <ci> pi </ci> instead of the construct <pi/>.
  • Similarly, when a Model object is provided, SId values of user-defined functions present in the Model will be used preferentially over pre-defined MathML functions. For example, if the passed-in Model contains a FunctionDefinition with the identifier "<code>sin</code>", that function will be used instead of the predefined MathML function <sin/>.

To obtain the default configuration values, callers can use the function libsbml.SBML_getDefaultL3ParserSettings(). To change the configuration, callers can create an L3ParserSettings object, set the desired characteristics using the methods provided, and pass that object to libsbml.parseL3FormulaWithSettings().

See also
libsbml.parseL3FormulaWithSettings()
libsbml.parseL3Formula()
libsbml.parseL3FormulaWithModel()

Public Member Functions

def getModel
 
def getParseAvogadroCsymbol
 
def getParseCollapseMinus
 
def getParseLog
 
def getParseUnits
 
def setModel
 
def setParseAvogadroCsymbol
 
def setParseCollapseMinus
 
def setParseLog
 
def setParseUnits
 
def unsetModel
 

Member Function Documentation

def libsbml.L3ParserSettings.getModel (   self)

Python method signature(s):

getModel(L3ParserSettings self)   Model

Returns the Model object referenced by this L3ParserSettings object.

See also
setModel()
unsetModel()
def libsbml.L3ParserSettings.getParseAvogadroCsymbol (   self)

Python method signature(s):

getParseAvogadroCsymbol(L3ParserSettings self)   bool

Returns True if the current settings are oriented towards handling avogadro for SBML Level 3.

SBML Level 3 defines a symbol for representing the value of Avogadro's constant, but it is not defined in SBML Level 2. As a result, the text-string formula parser must behave differently depending on which SBML Level is being targeted.

Returns
A boolean indicating which mode is currently set; the value is one of the following possibilities:
See also
setParseAvogadroCsymbol()
def libsbml.L3ParserSettings.getParseCollapseMinus (   self)

Python method signature(s):

getParseCollapseMinus(L3ParserSettings self)   bool

Returns a flag indicating the current behavior set for handling multiple unary minuses in formulas.

This setting affects two behaviors. First, pairs of multiple unary minuses in a row (e.g., "<code>- -3</code>") can be collapsed and ignored in the input, or the multiple minuses can be preserved in the AST node tree that is generated by the parser. Second, minus signs in front of numbers can be collapsed into the number node itself; for example, a "<code>- 4.1</code>" can be turned into a single ASTNode of type AST_REAL with a value of -4.1, or it can be turned into a node of type AST_MINUS having a child node of type AST_REAL. This method lets you tell the parser which behavior to use—either collapse minuses or always preserve them. The two possibilities are represented using the following constants:

Returns
A boolean, one of L3P_COLLAPSE_UNARY_MINUS or L3P_EXPAND_UNARY_MINUS.
See also
setParseCollapseMinus()
def libsbml.L3ParserSettings.getParseLog (   self)

Python method signature(s):

getParseLog(L3ParserSettings self)   long

Returns the current setting indicating what to do with formulas containing the function log with one argument.

The function log with a single argument ("<code>log(x)</code>") can be parsed as log10(x), ln(x), or treated as an error, as desired.

Returns
One of following three constants:
See also
setParseLog()
def libsbml.L3ParserSettings.getParseUnits (   self)

Python method signature(s):

getParseUnits(L3ParserSettings self)   bool

Returns if the current settings allow units in text-string mathematical formulas.

In SBML Level 2, there is no means of associating a unit of measurement with a pure number in a formula, while SBML Level 3 does define a syntax for this. In Level 3, MathML <cn> elements can have an attribute named units placed in the SBML namespace, which can be used to indicate the units to be associated with the number. The text-string infix formula parser allows units to be placed after raw numbers; they are interpreted as unit identifiers for units defined by the SBML specification or in the containing Model object. Some examples include: "<code>4 mL</code>", "<code>2.01 Hz</code>", "<code>3.1e-6 M</code>", and "<code>(5/8) inches</code>". To produce a valid SBML model, there must either exist a UnitDefinition corresponding to the identifier of the unit, or the unit must be defined in Table 2 of the SBML specification.

Since SBML Level 2 does not have the ability to associate units with pure numbers, the value should be set to False when parsing text-string formulas intended for use in SBML Level 2 documents.

Returns
A boolean indicating whether to parse units:
  • L3P_PARSE_UNITS (value = True): parse units in the text-string formula.
  • L3P_NO_UNITS (value = false): treat units in the text-string formula as errors.
See also
setParseUnits()
def libsbml.L3ParserSettings.setModel (   self,
  args 
)

{core}

A helper class for controlling the behavior of the text-string formula parser.

This class of objects is defined by libSBML only and has no direct equivalent in terms of SBML components. This class is not prescribed by the SBML specifications, although it is used to implement features defined in SBML.

The function libsbml.parseL3FormulaWithSettings(), along with its variants libsbml.parseFormula() and libsbml.parseL3FormulaWithModel(), are the interfaces to a parser for mathematical formulas expressed as text strings. The parser converts the text-string formulas into Abstract Syntax Trees (ASTs), represented in libSBML using ASTNode objects. Compared to the parser implemented by the function libsbml.parseFormula(), which was designed primarily for converting the mathematical formula strings in SBML Level 1, the 'L3' variant of the parser accepts an extended formula syntax. It also has a number of configurable behaviors. This class (L3ParserSettings) is an object used to communicate the configuration settings with callers.

The following aspects of the parser are configurable:

  • The function log with a single argument ("<code>log(x)</code>") can be parsed as log10(x), ln(x), or treated as an error, as desired.
  • Unary minus signs can be collapsed or preserved; that is, sequential pairs of unary minuses (e.g., "<code>- -3</code>") can be removed from the input entirely and single unary minuses can be incorporated into the number node, or all minuses can be preserved in the AST node structure.
  • Parsing of units embedded in the input string can be turned on and off.
  • The string avogadro can be parsed as a MathML csymbol or as an identifier.
  • A Model object may optionally be provided to the parser using the variant function calllibsbml.SBML_parseL3FormulaWithModel(). or stored in a L3ParserSettings object passed to the variant function libsbml.parseL3FormulaWithSettings(). When a Model object is provided, identifiers (values of type SId) from that model are used in preference to pre-defined MathML definitions. More precisely, the Model entities whose identifiers will shadow identical symbols in the mathematical formula are: Species, Compartment, Parameter, Reaction, and SpeciesReference. For instance, if the parser is given a Model containing a Species with the identifier "<code>pi</code>", and the formula to be parsed is "<code>3*pi</code>", the MathML produced will contain the construct <ci> pi </ci> instead of the construct <pi/>.
  • Similarly, when a Model object is provided, SId values of user-defined functions present in the Model will be used preferentially over pre-defined MathML functions. For example, if the passed-in Model contains a FunctionDefinition with the identifier "<code>sin</code>", that function will be used instead of the predefined MathML function <sin/>.

To obtain the default configuration values, callers can use the function libsbml.SBML_getDefaultL3ParserSettings(). To change the configuration, callers can create an L3ParserSettings object, set the desired characteristics using the methods provided, and pass that object to libsbml.parseL3FormulaWithSettings().

See also
libsbml.parseL3FormulaWithSettings()
libsbml.parseL3Formula()
libsbml.parseL3FormulaWithModel() Python method signature(s):
setModel(L3ParserSettings self, Model model)

Sets the model reference in this L3ParserSettings object.

When a Model object is provided, identifiers (values of type SId) from that model are used in preference to pre-defined MathML definitions. More precisely, the Model entities whose identifiers will shadow identical symbols in the mathematical formula are: Species, Compartment, Parameter, Reaction, and SpeciesReference. For instance, if the parser is given a Model containing a Species with the identifier "<code>pi</code>", and the formula to be parsed is "<code>3*pi</code>", the MathML produced will contain the construct <ci> pi </ci> instead of the construct <pi/>. Similarly, when a Model object is provided, SId values of user-defined functions present in the Model will be used preferentially over pre-defined MathML functions. For example, if the passed-in Model contains a FunctionDefinition with the identifier "<code>sin</code>", that function will be used instead of the predefined MathML function <sin/>.

Parameters
modela Model object to be used for disambiguating identifiers
Warning
This does not copy the Model object. This means that modifications made to the object after invoking this method may affect parsing behavior.
See also
getModel()
unsetModel()
def libsbml.L3ParserSettings.setParseAvogadroCsymbol (   self,
  args 
)

Python method signature(s):

setParseAvogadroCsymbol(L3ParserSettings self, bool l2only)

Sets the parser's behavior in handling the string avogadro in mathematical formulas.

SBML Level 3 defines a symbol for representing the value of Avogadro's constant, but it is not defined in SBML Level 2. As a result, the text-string formula parser must behave differently depending on which SBML Level is being targeted. The argument to this method can be one of two values:

Since SBML Level 2 does not define a symbol for Avogadro's constant, the value should be set to False when parsing text-string formulas intended for use in SBML Level 2 documents.

Parameters
l2onlya boolean value (one of the constants L3P_AVOGADRO_IS_CSYMBOL or L3P_AVOGADRO_IS_NAME) indicating how the string avogadro should be treated when encountered in a formula.
See also
getParseAvogadroCsymbol()
def libsbml.L3ParserSettings.setParseCollapseMinus (   self,
  args 
)

Python method signature(s):

setParseCollapseMinus(L3ParserSettings self, bool collapseminus)

Sets the behavior for handling unary minuses appearing in mathematical formulas.

This setting affects two behaviors. First, pairs of multiple unary minuses in a row (e.g., "<code>- -3</code>") can be collapsed and ignored in the input, or the multiple minuses can be preserved in the AST node tree that is generated by the parser. Second, minus signs in front of numbers can be collapsed into the number node itself; for example, a "<code>- 4.1</code>" can be turned into a single ASTNode of type AST_REAL with a value of -4.1, or it can be turned into a node of type AST_MINUS having a child node of type AST_REAL. This method lets you tell the parser which behavior to use—either collapse minuses or always preserve them. The two possibilities are represented using the following constants:

Parameters
collapseminusa boolean value (one of the constants L3P_COLLAPSE_UNARY_MINUS or L3P_EXPAND_UNARY_MINUS) indicating how unary minus signs in the input should be handled.
See also
getParseCollapseMinus()
def libsbml.L3ParserSettings.setParseLog (   self,
  args 
)

Python method signature(s):

setParseLog(L3ParserSettings self, long type)

Sets the behavior for handling log in mathematical formulas.

The function log with a single argument ("<code>log(x)</code>") can be parsed as log10(x), ln(x), or treated as an error, as desired.

Parameters
typea constant, one of following three possibilities:
See also
getParseLog()
def libsbml.L3ParserSettings.setParseUnits (   self,
  args 
)

Python method signature(s):

setParseUnits(L3ParserSettings self, bool units)

Sets the parser's behavior in handling units associated with numbers in a mathematical formula.

In SBML Level 2, there is no means of associating a unit of measurement with a pure number in a formula, while SBML Level 3 does define a syntax for this. In Level 3, MathML <cn> elements can have an attribute named units placed in the SBML namespace, which can be used to indicate the units to be associated with the number. The text-string infix formula parser allows units to be placed after raw numbers; they are interpreted as unit identifiers for units defined by the SBML specification or in the containing Model object. Some examples include: "<code>4 mL</code>", "<code>2.01 Hz</code>", "<code>3.1e-6 M</code>", and "<code>(5/8) inches</code>". To produce a valid SBML model, there must either exist a UnitDefinition corresponding to the identifier of the unit, or the unit must be defined in Table 2 of the SBML specification.

Parameters
unitsA boolean indicating whether to parse units:
  • L3P_PARSE_UNITS (value = True): parse units in the text-string formula.
  • L3P_NO_UNITS (value = false): treat units in the text-string formula as errors.
See also
getParseUnits()
def libsbml.L3ParserSettings.unsetModel (   self)

Python method signature(s):

unsetModel(L3ParserSettings self)

Sets the Model reference in this L3ParserSettings object to None.

See also
setModel()
getModel()