|
libSBML C++ API
5.20.2
|
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.
LibSBML implements facilities for verifying that a given SBML document is valid according to the SBML specifications; it also exposes the validation interface so that user programs and SBML Level 3 package authors may use the facilities to implement new validators. The entry point for this is the SBMLValidator class.
The subclass SBMLInternalValidator embodies the implementation of the consistency-checking methods defined on SBMLDocument. The methods SBMLDocument::setConsistencyChecks(), SBMLDocument::checkConsistency(), SBMLDocument::checkInternalConsistency() and other method of that sort are in fact implemented by SBMLInternalValidator. These validations are all performed on the internal (in-memory) representation of an SBML model.
Users should not need to call SBMLInternalValidator methods directly, since the interface is already provided on SBMLDocument. However, this class is exposed in case users would like to implement new or additional validations by extending this class (SBMLInternalValidator) or using this class as an example of how to implement such validators.
Public Member Functions | |
| unsigned int | checkConsistency (bool writeDocument=false) |
| Performs consistency checking and validation on this SBML document. More... | |
| unsigned int | checkInternalConsistency () |
| Performs consistency checking on libSBML's internal representation of an SBML Model. More... | |
| unsigned int | checkL1Compatibility () |
| Performs a set of consistency checks on the document to establish whether it is compatible with SBML Level 1 and can be converted to Level 1. More... | |
| unsigned int | checkL2v1Compatibility () |
| Performs a set of consistency checks on the document to establish whether it is compatible with SBML Level 2 Version 1 and can be converted to Level 2 Version 1. More... | |
| unsigned int | checkL2v2Compatibility () |
| Performs a set of consistency checks on the document to establish whether it is compatible with SBML Level 2 Version 2 and can be converted to Level 2 Version 2. More... | |
| unsigned int | checkL2v3Compatibility () |
| Performs a set of consistency checks on the document to establish whether it is compatible with SBML Level 2 Version 3 and can be converted to Level 2 Version 3. More... | |
| unsigned int | checkL2v4Compatibility () |
| Performs a set of consistency checks on the document to establish whether it is compatible with SBML Level 2 Version 4 and can be converted to Level 2 Version 4. More... | |
| unsigned int | checkL2v5Compatibility () |
| Performs a set of consistency checks on the document to establish whether it is compatible with SBML Level 2 Version 5 and can be converted to Level 2 Version 5. More... | |
| unsigned int | checkL3v1Compatibility () |
| Performs a set of consistency checks on the document to establish whether it is compatible with SBML Level 3 Version 1 and can be converted to Level 3 Version 1. More... | |
| unsigned int | checkL3v2Compatibility () |
| Performs a set of consistency checks on the document to establish whether it is compatible with SBML Level 3 Version 2 and can be converted to Level 3 Version 2. More... | |
| virtual void | clearFailures () |
| Clears this validator's list of failures. More... | |
| virtual SBMLValidator * | clone () const |
| Creates and returns a deep copy of this SBMLValidator object. More... | |
| unsigned char | getApplicableValidators () const |
| unsigned char | getConversionValidators () const |
| virtual SBMLDocument * | getDocument () |
| Returns the current SBML document in use by this validator. More... | |
| virtual const SBMLDocument * | getDocument () const |
| Returns the current SBML document in use by this validator. More... | |
| SBMLErrorLog * | getErrorLog () |
| Returns the list of errors or warnings logged during parsing, consistency checking, or attempted translation of this model. More... | |
| SBMLError * | getFailure (unsigned int n) const |
| Returns the failure object at index n in this validator's list of failures logged during the last run. More... | |
| const std::vector< SBMLError > & | getFailures () const |
| Returns a list of SBMLError objects (if any) that were logged by the last run of this validator. More... | |
| Model * | getModel () |
| Returns the Model object stored in the SBMLDocument. More... | |
| const Model * | getModel () const |
| Returns the Model object stored in the SBMLDocument. More... | |
| unsigned int | getNumFailures () const |
| Returns the number of failures encountered in the last validation run. More... | |
| void | logFailure (const SBMLError &err) |
| Adds the given failure to this list of Validators failures. More... | |
| SBMLInternalValidator () | |
| Constructor. More... | |
| SBMLInternalValidator (const SBMLInternalValidator &orig) | |
| Copy constructor; creates a copy of an SBMLInternalValidator object. More... | |
| void | setApplicableValidators (unsigned char appl) |
| Set the current list of validators to be applied. More... | |
| void | setConsistencyChecks (SBMLErrorCategory_t category, bool apply) |
| Controls the consistency checks that are performed when SBMLDocument::checkConsistency() is called. More... | |
| void | setConsistencyChecksForConversion (SBMLErrorCategory_t category, bool apply) |
| Controls the consistency checks that are performed when SBMLDocument::setLevelAndVersion() is called. More... | |
| void | setConversionValidators (unsigned char appl) |
| Set the current list of conversion validators to be applied. More... | |
| virtual int | setDocument (const SBMLDocument *doc) |
| Sets the current SBML document to the given SBMLDocument object. More... | |
| virtual unsigned int | validate () |
| Runs the validations. More... | |
| unsigned int | validate (const SBMLDocument &d) |
| Validates the given SBMLDocument object. More... | |
| unsigned int | validate (const std::string &filename) |
Validates the SBML document located at the given filename. More... | |
| virtual | ~SBMLInternalValidator () |
| Destroy this object. More... | |
| SBMLInternalValidator::SBMLInternalValidator | ( | ) |
Constructor.
| SBMLInternalValidator::SBMLInternalValidator | ( | const SBMLInternalValidator & | orig | ) |
Copy constructor; creates a copy of an SBMLInternalValidator object.
| orig | the object to copy. |
|
virtual |
Destroy this object.
| unsigned int SBMLInternalValidator::checkConsistency | ( | bool | writeDocument = false | ) |
Performs consistency checking and validation on this SBML document.
If this method returns a nonzero value (meaning, one or more consistency checks have failed for SBML document), the failures may be due to warnings or errors. Callers should inspect the severity flag in the individual SBMLError objects returned by SBMLDocument::getError() to determine the nature of the failures.
| writeDocument | by default checkConsistency will write the document in order to determine all errors for the document. This will also clear the error log. Setting this parameter to false will skip this additional step but might not find all errors. |
| unsigned int SBMLInternalValidator::checkInternalConsistency | ( | ) |
Performs consistency checking on libSBML's internal representation of an SBML Model.
Callers should query the results of the consistency check by calling SBMLDocument::getError().
The distinction between this method and SBMLDocument::checkConsistency() is that this method reports on fundamental syntactic and structural errors that violate the XML Schema for SBML; by contrast, SBMLDocument::checkConsistency() performs more elaborate model verifications and also validation according to the validation rules written in the appendices of the SBML Level 2 Versions 2–4 specification documents.
| unsigned int SBMLInternalValidator::checkL1Compatibility | ( | ) |
Performs a set of consistency checks on the document to establish whether it is compatible with SBML Level 1 and can be converted to Level 1.
Callers should query the results of the consistency check by calling SBMLDocument::getError().
| unsigned int SBMLInternalValidator::checkL2v1Compatibility | ( | ) |
Performs a set of consistency checks on the document to establish whether it is compatible with SBML Level 2 Version 1 and can be converted to Level 2 Version 1.
Callers should query the results of the consistency check by calling SBMLDocument::getError().
| unsigned int SBMLInternalValidator::checkL2v2Compatibility | ( | ) |
Performs a set of consistency checks on the document to establish whether it is compatible with SBML Level 2 Version 2 and can be converted to Level 2 Version 2.
Callers should query the results of the consistency check by calling SBMLDocument::getError().
| unsigned int SBMLInternalValidator::checkL2v3Compatibility | ( | ) |
Performs a set of consistency checks on the document to establish whether it is compatible with SBML Level 2 Version 3 and can be converted to Level 2 Version 3.
Callers should query the results of the consistency check by calling SBMLDocument::getError().
| unsigned int SBMLInternalValidator::checkL2v4Compatibility | ( | ) |
Performs a set of consistency checks on the document to establish whether it is compatible with SBML Level 2 Version 4 and can be converted to Level 2 Version 4.
Callers should query the results of the consistency check by calling SBMLDocument::getError().
| unsigned int SBMLInternalValidator::checkL2v5Compatibility | ( | ) |
Performs a set of consistency checks on the document to establish whether it is compatible with SBML Level 2 Version 5 and can be converted to Level 2 Version 5.
Callers should query the results of the consistency check by calling SBMLDocument::getError().
| unsigned int SBMLInternalValidator::checkL3v1Compatibility | ( | ) |
Performs a set of consistency checks on the document to establish whether it is compatible with SBML Level 3 Version 1 and can be converted to Level 3 Version 1.
Callers should query the results of the consistency check by calling SBMLDocument::getError().
| unsigned int SBMLInternalValidator::checkL3v2Compatibility | ( | ) |
Performs a set of consistency checks on the document to establish whether it is compatible with SBML Level 3 Version 2 and can be converted to Level 3 Version 2.
Callers should query the results of the consistency check by calling SBMLDocument::getError().
|
virtualinherited |
Clears this validator's list of failures.
If you are validating multiple SBML documents with the same validator, call this method after you have processed the list of failures from the last validation run and before validating the next document.
|
virtual |
Creates and returns a deep copy of this SBMLValidator object.
Reimplemented from SBMLValidator.
| unsigned char SBMLInternalValidator::getApplicableValidators | ( | ) | const |
| unsigned char SBMLInternalValidator::getConversionValidators | ( | ) | const |
|
virtualinherited |
Returns the current SBML document in use by this validator.
|
virtualinherited |
Returns the current SBML document in use by this validator.
|
inherited |
Returns the list of errors or warnings logged during parsing, consistency checking, or attempted translation of this model.
Note that this refers to the SBMLDocument object's error log (i.e., the list returned by SBMLDocument::getErrorLog()). That list of errors and warnings is separate from the validation failures tracked by this validator (i.e., the list returned by getFailures()).
|
inherited |
Returns the failure object at index n in this validator's list of failures logged during the last run.
Callers should use getNumFailures() first, to find out the number of entries in this validator's list of failures.
| n | an integer indicating the index of the object to return from the failures list; index values start at 0. |
|
inherited |
Returns a list of SBMLError objects (if any) that were logged by the last run of this validator.
|
inherited |
Returns the Model object stored in the SBMLDocument.
It is important to note that this method does not create a Model instance. The model in the SBMLDocument must have been created at some prior time, for example using SBMLDocument::createModel() or SBMLDocument::setModel(). This method returns NULL if a model does not yet exist.
|
inherited |
Returns the Model object stored in the SBMLDocument.
It is important to note that this method does not create a Model instance. The model in the SBMLDocument must have been created at some prior time, for example using SBMLDocument::createModel() or SBMLDocument::setModel(). This method returns NULL if a model does not yet exist.
|
inherited |
Returns the number of failures encountered in the last validation run.
This method returns the number of failures logged by this validator. This number only reflects this validator's actions; the number may not be the same as the number of errors and warnings logged on the SBMLDocument object's error log (i.e., the object returned by SBMLDocument::getErrorLog()), because other parts of libSBML may log errors and warnings beyond those found by this validator.
|
inherited |
Adds the given failure to this list of Validators failures.
| err | an SBMLError object representing an error or warning. |
| void SBMLInternalValidator::setApplicableValidators | ( | unsigned char | appl | ) |
Set the current list of validators to be applied.
| appl | the mask of validators to be applied. |
| void SBMLInternalValidator::setConsistencyChecks | ( | SBMLErrorCategory_t | category, |
| bool | apply | ||
| ) |
Controls the consistency checks that are performed when SBMLDocument::checkConsistency() is called.
This method works by adding or subtracting consistency checks from the set of all possible checks that SBMLDocument::checkConsistency() knows how to perform. This method may need to be called multiple times in order to achieve the desired combination of checks. The first argument (category) in a call to this method indicates the category of consistency/error checks that are to be turned on or off, and the second argument (apply, a boolean) indicates whether to turn it on (value of true) or off (value of false).
The possible categories (values to the argument category) are the set of values from the enumeration SBMLErrorCategory_t. The following are the possible choices:
LIBSBML_CAT_GENERAL_CONSISTENCY: Correctness and consistency of specific SBML language constructs. Performing this set of checks is highly recommended. With respect to the SBML specification, these concern failures in applying the validation rules numbered 2xxxx in the Level 2 Versions 2–4 and Level 3 Versions 1–2 specifications.
LIBSBML_CAT_IDENTIFIER_CONSISTENCY: Correctness and consistency of identifiers used for model entities. An example of inconsistency would be using a species identifier in a reaction rate formula without first having declared the species. With respect to the SBML specification, these concern failures in applying the validation rules numbered 103xx in the Level 2 Versions 2–4 and Level 3 Versions 1–2 specifications.
LIBSBML_CAT_UNITS_CONSISTENCY: Consistency of measurement units associated with quantities in a model. With respect to the SBML specification, these concern failures in applying the validation rules numbered 105xx in the Level 2 Versions 2–4 and Level 3 Versions 1–2 specifications.
LIBSBML_CAT_MATHML_CONSISTENCY: Syntax of MathML constructs. With respect to the SBML specification, these concern failures in applying the validation rules numbered 102xx in the Level 2 Versions 2–4 and Level 3 Versions 1–2 specifications.
LIBSBML_CAT_SBO_CONSISTENCY: Consistency and validity of SBO identifiers (if any) used in the model. With respect to the SBML specification, these concern failures in applying the validation rules numbered 107xx in the Level 2 Versions 2–4 and Level 3 Versions 1–2 specifications.
LIBSBML_CAT_OVERDETERMINED_MODEL: Static analysis of whether the system of equations implied by a model is mathematically overdetermined. With respect to the SBML specification, this is validation rule #10601 in the Level 2 Versions 2–4 and Level 3 Versions 1–2 specifications.
By default, all validation checks are applied to the model in an SBMLDocument object unless SBMLDocument::setConsistencyChecks() is called to indicate that only a subset should be applied. Further, this default (i.e., performing all checks) applies separately to each new SBMLDocument object created. In other words, each time a model is read using SBMLReader::readSBML(), SBMLReader::readSBMLFromString(), or the global functions readSBML() and readSBMLFromString(), a new SBMLDocument is created and for that document, a call to SBMLDocument::checkConsistency() will default to applying all possible checks. Calling programs must invoke SBMLDocument::setConsistencyChecks() for each such new model if they wish to change the consistency checks applied.
| category | a value drawn from SBMLErrorCategory_t indicating the consistency checking/validation to be turned on or off. |
| apply | a boolean indicating whether the checks indicated by category should be applied or not. |
| void SBMLInternalValidator::setConsistencyChecksForConversion | ( | SBMLErrorCategory_t | category, |
| bool | apply | ||
| ) |
Controls the consistency checks that are performed when SBMLDocument::setLevelAndVersion() is called.
This method works by adding or subtracting consistency checks from the set of all possible checks that may be performed to avoid conversion to or from an invalid document. This method may need to be called multiple times in order to achieve the desired combination of checks. The first argument (category) in a call to this method indicates the category of consistency/error checks that are to be turned on or off, and the second argument (apply, a boolean) indicates whether to turn it on (value of true) or off (value of false).
The possible categories (values to the argument category) are the set of values from the enumeration SBMLErrorCategory_t. The following are the possible choices:
LIBSBML_CAT_GENERAL_CONSISTENCY: Correctness and consistency of specific SBML language constructs. Performing this set of checks is highly recommended. With respect to the SBML specification, these concern failures in applying the validation rules numbered 2xxxx in the Level 2 Versions 2–4 and Level 3 Versions 1–2 specifications.
LIBSBML_CAT_IDENTIFIER_CONSISTENCY: Correctness and consistency of identifiers used for model entities. An example of inconsistency would be using a species identifier in a reaction rate formula without first having declared the species. With respect to the SBML specification, these concern failures in applying the validation rules numbered 103xx in the Level 2 Versions 2–4 and Level 3 Versions 1–2 specifications.
LIBSBML_CAT_UNITS_CONSISTENCY: Consistency of measurement units associated with quantities in a model. With respect to the SBML specification, these concern failures in applying the validation rules numbered 105xx in the Level 2 Versions 2–4 and Level 3 Versions 1–2 specifications.
LIBSBML_CAT_MATHML_CONSISTENCY: Syntax of MathML constructs. With respect to the SBML specification, these concern failures in applying the validation rules numbered 102xx in the Level 2 Versions 2–4 and Level 3 Versions 1–2 specifications.
LIBSBML_CAT_SBO_CONSISTENCY: Consistency and validity of SBO identifiers (if any) used in the model. With respect to the SBML specification, these concern failures in applying the validation rules numbered 107xx in the Level 2 Versions 2–4 and Level 3 Versions 1–2 specifications.
LIBSBML_CAT_OVERDETERMINED_MODEL: Static analysis of whether the system of equations implied by a model is mathematically overdetermined. With respect to the SBML specification, this is validation rule #10601 in the Level 2 Versions 2–4 and Level 3 Versions 1–2 specifications.
By default, all validation checks are applied to the model in an SBMLDocument object unless SBMLDocument::setConsistencyChecks() is called to indicate that only a subset should be applied. Further, this default (i.e., performing all checks) applies separately to each new SBMLDocument object created. In other words, each time a model is read using SBMLReader::readSBML(), SBMLReader::readSBMLFromString(), or the global functions readSBML() and readSBMLFromString(), a new SBMLDocument is created and for that document, a call to SBMLDocument::checkConsistency() will default to applying all possible checks. Calling programs must invoke SBMLDocument::setConsistencyChecks() for each such new model if they wish to change the consistency checks applied.
| category | a value drawn from SBMLErrorCategory_t indicating the consistency checking/validation to be turned on or off. |
| apply | a boolean indicating whether the checks indicated by category should be applied or not. |
| void SBMLInternalValidator::setConversionValidators | ( | unsigned char | appl | ) |
Set the current list of conversion validators to be applied.
| appl | the mask of validators to be applied. |
|
virtualinherited |
Sets the current SBML document to the given SBMLDocument object.
| doc | the document to use for this validation. |
|
virtual |
Runs the validations.
This runs the validations that were previously enabled via methods such as SBMLDocument::setConsistencyChecks().
Reimplemented from SBMLValidator.
|
inherited |
Validates the given SBMLDocument object.
This is identical to calling setDocument() followed by validate().
| d | the SBML document to validate. |
|
inherited |
Validates the SBML document located at the given filename.
This is a convenience method that saves callers the trouble of using SBMLReader to read the document first.
| filename | the path to the file to be read and validated. |