libSBML Python API  5.11.0
libsbml.L3ParserSettings Class Reference
Inheritance diagram for libsbml.L3ParserSettings:
[legend]

Detailed Description

Controls the behavior of the Level 3 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 parseL3FormulaWithSettings(), along with its variants parseL3Formula() and parseL3FormulaWithModel(), are the interfaces to a parser for mathematical formulas written as text strings. The inverse function is formulaToL3String() and its variants such as formulaToL3StringWithSettings(). The parsers and the formula writers convert between a text-string representation of mathematical formulas and Abstract Syntax Trees (ASTs), represented in libSBML using ASTNode objects. Compared to the parser and writer implemented by the functions parseFormula() and formulaToString(), which were designed primarily for converting the mathematical formula strings in SBML Level 1, the SBML Level 3 or 'L3' variants of the parser and writer use an extended formula syntax. They also have 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 using L3ParserSettings objects. (For the formula writer, only a subset of these settings is relevant; please see the documentation for formulaToL3StringWithSettings() for more information about which ones).

  • A Model object may optionally be provided to use identifiers (values of type SId) from the model in preference to pre-defined MathML symbols 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 "pi", and the formula to be parsed is "3*pi", the MathML produced by the parser will contain the construct <ci> pi </ci> instead of the construct <pi/>. Another example, if the passed-in Model contains a FunctionDefinition with the identifier "sin", that function will be used instead of the predefined MathML function <sin/>.
  • The function log with a single argument ("log(x)") can be parsed as log10(x), ln(x), or treated as an error, as desired.
  • Unary minus signs can be either collapsed or preserved; that is, the parser can either (1) remove sequential pairs of unary minuses (e.g., "- -3") from the input and incorporate single unary minuses into the number node, or (2) preserve all minuses in the AST node structure, turning them into ASTNode objects of type AST_MINUS.
  • The character sequence "number id" can be interpreted as a numerical value number followed by units of measurement indicated by id, or it can be treated as a syntax error. (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.)
  • The symbol avogadro can be parsed either as a MathML csymbol or as a identifier. More specifically, "avogadro" can be treated as an ASTNode of type AST_NAME_AVOGADRO or of type AST_NAME.
  • Strings that match built-in functions and constants can either be parsed as a match regardless of capitalization, or may be required to be all-lower-case to be considered a match.
  • LibSBML plug-ins implementing support for SBML Level 3 packages may introduce extensions to the syntax understood by the parser. The precise nature of the extensions will be documented by the individual package plug-ins. An example of a possible extension is a notation for vectors and arrays, introduced by the SBML Level 3 Arrays package.

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

See also
parseL3Formula()
parseL3FormulaWithSettings()
parseL3FormulaWithModel()
parseFormula()
formulaToL3StringWithSettings()
formulaToL3String()
formulaToString()
getDefaultL3ParserSettings()

Public Member Functions

def __init__ (self, args)
  Controls the behavior of the Level 3 formula parser. More...
 
def getComparisonCaseSensitivity (self)
 Returns True if the parser is configured to match built-in symbols in a case-insensitive way. More...
 
def getModel (self)
 Returns the Model object referenced by this L3ParserSettings object. More...
 
def getParseAvogadroCsymbol (self)
 Indicates the current behavior set for handling avogadro for SBML Level 3. More...
 
def getParseCollapseMinus (self)
 Indicates the current behavior set for handling multiple unary minuses in formulas. More...
 
def getParseLog (self)
 Indicates the current behavior set for handling the function log with one argument. More...
 
def getParseUnits (self)
 Indicates the current behavior set for handling units in text-string mathematical formulas. More...
 
def setComparisonCaseSensitivity (self, strcmp)
 Sets the parser's behavior with respect to case sensitivity for recognizing predefined symbols. More...
 
def setModel (self, model)
 Sets the model reference in this L3ParserSettings object. More...
 
def setParseAvogadroCsymbol (self, l2only)
 Sets the parser's behavior in handling the symbol avogadro in mathematical formulas. More...
 
def setParseCollapseMinus (self, collapseminus)
 Sets the behavior for handling unary minuses appearing in mathematical formulas. More...
 
def setParseLog (self, type)
 Sets the behavior for handling log in mathematical formulas. More...
 
def setParseUnits (self, units)
 Sets the parser's behavior in handling units associated with numbers in a mathematical formula. More...
 
def setPlugins (self, sbmlns)
 Set up the plugins for this L3ParserSettings, based on the SBMLNamespaces object. More...
 
def unsetModel (self)
 Unsets the Model reference in this L3ParserSettings object. More...
 

Member Function Documentation

def libsbml.L3ParserSettings.getComparisonCaseSensitivity (   self)

Returns True if the parser is configured to match built-in symbols in a case-insensitive way.

getComparisonCaseSensitivity()   bool
By default (which is the value L3P_COMPARE_BUILTINS_CASE_INSENSITIVE), the parser compares symbols in a case insensitive manner for built-in functions such as 'sin' and 'piecewise', and for constants such as 'True' and 'avogadro'. Setting this option to L3P_COMPARE_BUILTINS_CASE_SENSITIVE causes the parser to become case sensitive. In that mode, for example, the symbols 'sin' and 'True' will match the built-in values, but the symbols 'SIN', 'Sin', 'True', 'TRUE', and so on, will not.
Returns
True if matches are done in a case-sensitive manner, and False if the parser will recognize built-in functions and constants regardless of case,.
See also
setComparisonCaseSensitivity()
def libsbml.L3ParserSettings.getModel (   self)

Returns the Model object referenced by this L3ParserSettings object.

getModel()   Model
When a Model object is provided, identifiers (values of type SId) from that model are used in preference to pre-defined MathML symbol 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 "pi", and the formula to be parsed is "3*pi", 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 "sin", that function will be used instead of the predefined MathML function <sin/>.
See also
setModel()
unsetModel()
def libsbml.L3ParserSettings.getParseAvogadroCsymbol (   self)

Indicates the current behavior set for handling avogadro for SBML Level 3.

getParseAvogadroCsymbol()   bool
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. For Level 3 documents, it can interpret instances of avogadro in the input as a reference to the MathML csymbol for Avogadro's constant defined in the SBML Level 3 specification. For Level 2, it must treat avogadro as just another plain symbol.

This method returns the current setting of the avogadro-handling behavior in this L3ParserSettings object. The possible values are as follows:

Returns
A boolean indicating which mode is currently set; one of L3P_AVOGADRO_IS_CSYMBOL or L3P_AVOGADRO_IS_NAME.
See also
setParseAvogadroCsymbol()
def libsbml.L3ParserSettings.getParseCollapseMinus (   self)

Indicates the current behavior set for handling multiple unary minuses in formulas.

getParseCollapseMinus()   bool
This setting affects two behaviors. First, pairs of multiple unary minuses in a row (e.g., "- -3") 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 "- 4.1" 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.
Returns
A boolean indicating the behavior currently set. The possible values are as follows:
See also
setParseCollapseMinus()
def libsbml.L3ParserSettings.getParseLog (   self)

Indicates the current behavior set for handling the function log with one argument.

getParseLog()   long

The function log with a single argument ("log(x)") can be parsed as log10(x), ln(x), or treated as an error, as desired. These three possible behaviors are indicated, respectively, by the values L3P_PARSE_LOG_AS_LOG10, L3P_PARSE_LOG_AS_LN, and L3P_PARSE_LOG_AS_ERROR.

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

Indicates the current behavior set for handling units in text-string mathematical formulas.

getParseUnits()   bool
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: "4 mL", "2.01 Hz", "3.1e-6 M", and "(5/8) inches". 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 Level 3 specification.

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

Returns
A boolean indicating whether to parse units. The possible values are as follows:
  • 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.setComparisonCaseSensitivity (   self,
  strcmp 
)

Sets the parser's behavior with respect to case sensitivity for recognizing predefined symbols.

setComparisonCaseSensitivity(bool strcmp)
By default (which is the value L3P_COMPARE_BUILTINS_CASE_INSENSITIVE), the parser compares symbols in a case insensitive manner for built-in functions such as 'sin' and 'piecewise', and for constants such as 'True' and 'avogadro'. Setting this option to L3P_COMPARE_BUILTINS_CASE_SENSITIVE causes the parser to become case sensitive. In that mode, for example, the symbols 'sin' and 'True' will match the built-in values, but the symbols 'SIN', 'Sin', 'True', 'TRUE', and so on, will not.
Parameters
strcmpa boolean indicating whether to be case sensitive (if True) or be case insensitive (if False).
See also
getComparisonCaseSensitivity()
def libsbml.L3ParserSettings.setModel (   self,
  model 
)

Sets the model reference in this L3ParserSettings object.

setModel(Model model)
When a Model object is provided, identifiers (values of type SId) from that model are used in preference to pre-defined MathML symbol 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 "pi", and the formula to be parsed is "3*pi", 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 "sin", 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 Model after invoking this method may affect parsing behavior, because the parser will query the current contents of the model.
See also
getModel()
unsetModel()
def libsbml.L3ParserSettings.setParseAvogadroCsymbol (   self,
  l2only 
)

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

setParseAvogadroCsymbol(bool l2only)
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. For Level 3 documents, it can interpret instances of avogadro in the input as a reference to the MathML csymbol for Avogadro's constant defined in the SBML Level 3 specification. For Level 2, it must treat avogadro as just another plain symbol.

This method allows callers to set the avogadro-handling behavior in this L3ParserSettings object. The possible values of l2only are as follows:

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

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

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

setParseCollapseMinus(bool collapseminus)
This setting affects two behaviors. First, pairs of multiple unary minuses in a row (e.g., "- -3") 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 "- 4.1" 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,
  type 
)

Sets the behavior for handling log in mathematical formulas.

setParseLog(long type)

The function log with a single argument ("log(x)") can be parsed as log10(x), ln(x), or treated as an error. These three behaviors are set, respectively, by using the value L3P_PARSE_LOG_AS_LOG10, L3P_PARSE_LOG_AS_LN, or L3P_PARSE_LOG_AS_ERROR for the type parameter.

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

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

setParseUnits(bool units)
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: "4 mL", "2.01 Hz", "3.1e-6 M", and "(5/8) inches". 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 Level 3 specification.

This method sets the formula parser's behavior with respect to units.

Parameters
unitsA boolean indicating whether to parse units. The possible values are as follows:
  • 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.setPlugins (   self,
  sbmlns 
)

Set up the plugins for this L3ParserSettings, based on the SBMLNamespaces object.

setPlugins(SBMLNamespaces sbmlns)

When a SBMLNamespaces object is provided, the parser will only interpret infix syntax understood by the core libSBML plus the packages indicated by the SBMLNamespaces objects provided. ASTNode objects returned by the L3Parser will contain those SBMLNamespaces objects, and will be used to parse certain constructs that may only be understood by packages (e.g., vectors for the SBML Level 3 'arrays' package). Note that by default, all packages that were compiled with this version of libSBML are included, so this function is most useful as a way to turn off certain namespaces, such as might be desired if your tool does not support vectors, for example.

Parameters
sbmlnsa SBMLNamespaces object to be used. If None is given as the value, all plugins will be loaded.
def libsbml.L3ParserSettings.unsetModel (   self)

Unsets the Model reference in this L3ParserSettings object.

unsetModel()

The effect of calling this method is to set the stored model value to None.

See also
setModel()
getModel()