libSBML C++ API  5.20.4
SBMLInternalValidator Class Reference
Inheritance diagram for SBMLInternalValidator:
[legend]

Detailed Description

Basic SBML consistency checks and other validations.

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 SBMLValidatorclone () const
 Creates and returns a deep copy of this SBMLValidator object. More...
 
unsigned char getApplicableValidators () const
 
unsigned char getConversionValidators () const
 
virtual SBMLDocumentgetDocument ()
 Returns the current SBML document in use by this validator. More...
 
virtual const SBMLDocumentgetDocument () const
 Returns the current SBML document in use by this validator. More...
 
SBMLErrorLoggetErrorLog ()
 Returns the list of errors or warnings logged during parsing, consistency checking, or attempted translation of this model. More...
 
SBMLErrorgetFailure (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...
 
ModelgetModel ()
 Returns the Model object stored in the SBMLDocument. More...
 
const ModelgetModel () 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...
 

Constructor & Destructor Documentation

◆ SBMLInternalValidator() [1/2]

SBMLInternalValidator::SBMLInternalValidator ( )

Constructor.

◆ SBMLInternalValidator() [2/2]

SBMLInternalValidator::SBMLInternalValidator ( const SBMLInternalValidator orig)

Copy constructor; creates a copy of an SBMLInternalValidator object.

Parameters
origthe object to copy.

◆ ~SBMLInternalValidator()

SBMLInternalValidator::~SBMLInternalValidator ( )
virtual

Destroy this object.

Member Function Documentation

◆ checkConsistency()

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.

Parameters
writeDocumentby 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.
Returns
the number of failed checks (errors) encountered.
See also
SBMLDocument::checkInternalConsistency()

◆ checkInternalConsistency()

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().

Returns
the number of failed checks (errors) encountered.

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.

See also
SBMLDocument::checkConsistency()

◆ checkL1Compatibility()

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().

Returns
the number of failed checks (errors) encountered.

◆ checkL2v1Compatibility()

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().

Returns
the number of failed checks (errors) encountered.

◆ checkL2v2Compatibility()

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().

Returns
the number of failed checks (errors) encountered.

◆ checkL2v3Compatibility()

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().

Returns
the number of failed checks (errors) encountered.

◆ checkL2v4Compatibility()

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().

Returns
the number of failed checks (errors) encountered.

◆ checkL2v5Compatibility()

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().

Returns
the number of failed checks (errors) encountered.

◆ checkL3v1Compatibility()

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().

Returns
the number of failed checks (errors) encountered.

◆ checkL3v2Compatibility()

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().

Returns
the number of failed checks (errors) encountered.

◆ clearFailures()

void SBMLValidator::clearFailures ( )
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.

See also
getFailures()

◆ clone()

SBMLValidator * SBMLInternalValidator::clone ( ) const
virtual

Creates and returns a deep copy of this SBMLValidator object.

Returns
the (deep) copy of this SBMLValidator object.

Reimplemented from SBMLValidator.

◆ getApplicableValidators()

unsigned char SBMLInternalValidator::getApplicableValidators ( ) const
Returns
the current list of selected validators.

◆ getConversionValidators()

unsigned char SBMLInternalValidator::getConversionValidators ( ) const
Returns
the current list of selected validators for conversion.

◆ getDocument() [1/2]

SBMLDocument * SBMLValidator::getDocument ( )
virtualinherited

Returns the current SBML document in use by this validator.

Returns
the current SBML document.
See also
setDocument()

◆ getDocument() [2/2]

const SBMLDocument * SBMLValidator::getDocument ( ) const
virtualinherited

Returns the current SBML document in use by this validator.

Returns
a const reference to the current SBML document.
See also
setDocument()

◆ getErrorLog()

SBMLErrorLog * SBMLValidator::getErrorLog ( )
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()).

Returns
the SBMLErrorLog used for the SBMLDocument.
See also
getFailures()

◆ getFailure()

SBMLError * SBMLValidator::getFailure ( unsigned int  n) const
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.

Parameters
nan integer indicating the index of the object to return from the failures list; index values start at 0.
Returns
the failure at the given index number.
See also
getNumFailures()

◆ getFailures()

const std::vector< SBMLError > & SBMLValidator::getFailures ( ) const
inherited

Returns a list of SBMLError objects (if any) that were logged by the last run of this validator.

Returns
a list of errors, warnings and other diagnostics logged during validation.
See also
clearFailures()

◆ getModel() [1/2]

Model * SBMLValidator::getModel ( )
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.

Returns
the Model contained in this validator's SBMLDocument object.
See also
SBMLDocument::setModel()
SBMLDocument::createModel()

◆ getModel() [2/2]

const Model * SBMLValidator::getModel ( ) const
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.

Returns
the Model contained in this validator's SBMLDocument object.
See also
SBMLDocument::setModel()
SBMLDocument::createModel()

◆ getNumFailures()

unsigned int SBMLValidator::getNumFailures ( ) const
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.

Returns
the number of errors logged by this validator.

◆ logFailure()

void SBMLValidator::logFailure ( const SBMLError err)
inherited

Adds the given failure to this list of Validators failures.

Parameters
erran SBMLError object representing an error or warning.
See also
getFailures()

◆ setApplicableValidators()

void SBMLInternalValidator::setApplicableValidators ( unsigned char  appl)

Set the current list of validators to be applied.

Parameters
applthe mask of validators to be applied.

◆ setConsistencyChecks()

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.

  • LIBSBML_CAT_MODELING_PRACTICE: Additional checks for recommended good modeling practice. (These are tests performed by libSBML and do not have equivalent SBML validation rules.)

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.

Parameters
categorya value drawn from SBMLErrorCategory_t indicating the consistency checking/validation to be turned on or off.
applya boolean indicating whether the checks indicated by category should be applied or not.
See also
SBMLDocument::checkConsistency()

◆ setConsistencyChecksForConversion()

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.

  • LIBSBML_CAT_MODELING_PRACTICE: Additional checks for recommended good modeling practice. (These are tests performed by libSBML and do not have equivalent SBML validation rules.)

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.

Parameters
categorya value drawn from SBMLErrorCategory_t indicating the consistency checking/validation to be turned on or off.
applya boolean indicating whether the checks indicated by category should be applied or not.
See also
SBMLDocument::setLevelAndVersion()

◆ setConversionValidators()

void SBMLInternalValidator::setConversionValidators ( unsigned char  appl)

Set the current list of conversion validators to be applied.

Parameters
applthe mask of validators to be applied.

◆ setDocument()

int SBMLValidator::setDocument ( const SBMLDocument doc)
virtualinherited

Sets the current SBML document to the given SBMLDocument object.

Parameters
docthe document to use for this validation.
Returns
integer value indicating success/failure of the function. The value is drawn from the enumeration OperationReturnValues_t. This particular function only does one thing irrespective of user input or object state, and thus will only return a single value:
See also
getDocument()

◆ validate() [1/3]

unsigned int SBMLInternalValidator::validate ( )
virtual

Runs the validations.

This runs the validations that were previously enabled via methods such as SBMLDocument::setConsistencyChecks().

Returns
the number of validation failures that occurred. The objects describing the actual failures can be retrieved using getFailures().

Reimplemented from SBMLValidator.

◆ validate() [2/3]

unsigned int SBMLValidator::validate ( const SBMLDocument d)
inherited

Validates the given SBMLDocument object.

This is identical to calling setDocument() followed by validate().

Parameters
dthe SBML document to validate.
Returns
the number of validation failures that occurred. The objects describing the actual failures can be retrieved using getFailures().

◆ validate() [3/3]

unsigned int SBMLValidator::validate ( const std::string &  filename)
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.

Parameters
filenamethe path to the file to be read and validated.
Returns
the number of validation failures that occurred. The objects describing the actual failures can be retrieved using getFailures().