Skip to content

validation

Helpers for validation and checking of SBML and libsbml operations.

ScopedLossCollector 

ScopedLossCollector(name, report)

Collect the losses of one document and report them once per group.

Writing a document can lose the same thing over and over: an annotation resource of a collection which cannot be canonicalized, an attribute the level and version of the document does not have. Reporting each of them on its own buries the one decision which fixes all of them under thousands of lines. Inside a scope every loss is collected under a key and the detail is logged at debug by the caller; when the outermost scope ends, one report per key is emitted, in the order of the keys. Outside a scope there is nothing to report at the end, so the caller reports the loss directly.

The collection is held in a ContextVar rather than in a module global: it belongs to the code which writes one document, and a thread starts with a fresh context in which the variable holds its default, so writing one document does not collect into the report of another.

The type variable K is the key the losses are grouped under, a string or a tuple of them, and V is what is collected for one key.

Construct a collector.

Parameters:

Name Type Description Default
name str

the name of the ContextVar, which is used for debugging only and should name the package and the kind of loss

 required
report Callable[[K, V], None]

called once per key when the outermost scope ends, in the order of the keys

 required

scope 

scope()

Collect the losses recorded inside and report them when it ends.

A scope inside an active one collects into it and reports nothing of its own, so that a document which is created and then annotated from a file is still reported once.

Yields:

Type Description
Generator[None]

None

group 

group(key, create)

Get the group of a key inside a scope, None outside one.

Parameters:

Name Type Description Default
key K

the key the loss is grouped under

 required
create Callable[[], V]

builds the group when the key is seen for the first time

 required

Returns:

Type Description
V | None

the group to record the loss in, None if no scope is active and
V | None

the caller has to report the loss itself

ConstructionDiagnostic dataclass 

ConstructionDiagnostic(
    code, severity, message, count=1, example=None
)

One grouped construction finding, without references to native objects.

ConstructionError 

ConstructionError(diagnostics)

Bases: ValueError

Strict construction rejected reported losses or undeclared targets.

Retain an immutable snapshot of all construction findings.

PreservationError 

PreservationError(diagnostics)

Bases: ValueError

A parse or write would discard reported source content.

Retain an immutable snapshot of the known preservation losses.

ValidationOptions dataclass 

ValidationOptions(
    log_errors=True,
    internal_consistency=True,
    general_consistency=True,
    identifier_consistency=True,
    mathml_consistency=True,
    units_consistency=True,
    sbo_consistency=True,
    overdetermined_model=True,
    modeling_practice=True,
)

Options for SBML validator.

Controls the consistency checks that are performed when SBMLDocument.checkConsistency() is called.

  • 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.

  • ìdentifier_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.

  • 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.

  • 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.

  • 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.

  • 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.

  • modeling_practise: 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.

  • internal_consistency: Additional checks that model is consistent XML.

  • log_errors Boolean flag to log errors.

fast classmethod 

fast(*, log_errors=True)

Check structure and identifiers without expensive unit analysis.

Use the default options for comprehensive validation before sharing or simulating a model. This preset leaves all other checks enabled.

SBMLErrorInfo dataclass 

SBMLErrorInfo(
    error_id,
    severity,
    severity_string,
    category,
    category_string,
    line,
    column,
    message,
    short_message,
    package,
)

Immutable snapshot of a libsbml SBMLError.

A libsbml error belongs to the error log of its document and is gone with the document, so a ValidationResult which holds the libsbml objects returns garbage once the validated document is freed. The snapshot holds plain values and offers the getters of libsbml.SBMLError which are used on results, so code written against the libsbml object keeps working.

from_error staticmethod 

from_error(error)

Take a snapshot of a libsbml error.

getErrorId 

getErrorId()

Get the error id.

getSeverity 

getSeverity()

Get the severity code.

getSeverityAsString 

getSeverityAsString()

Get the severity as string.

getCategory 

getCategory()

Get the category code.

getCategoryAsString 

getCategoryAsString()

Get the category as string.

getLine 

getLine()

Get the line.

getColumn 

getColumn()

Get the column.

getMessage 

getMessage()

Get the message.

getShortMessage 

getShortMessage()

Get the short message.

getPackage 

getPackage()

Get the package.

isInfo 

isInfo()

Check if the severity is informational (libsbml isInfo).

isWarning 

isWarning()

Check if the severity is warning (libsbml isWarning).

isError 

isError()

Check if the severity is error or fatal (libsbml isError).

isFatal 

isFatal()

Check if the severity is fatal (libsbml isFatal).

ValidationResult 

ValidationResult(errors=None, warnings=None)

Results of an SBMLDocument validation.

The errors and warnings are snapshots, they stay valid when the validated document is freed.

Initialize ValidationResult.

error_count property 

error_count

Get number of errors.

warning_count property 

warning_count

Get number of warnings.

all_count property 

all_count

Get number of errors and warnings.

from_results staticmethod 

from_results(results)

Parse from ValidationResult.

log 

log()

Log errors and warnings.

is_valid 

is_valid()

Get valid status (valid model), i.e., no errors.

is_perfect 

is_perfect()

Get perfect status (perfect model), i.e., no errors and warnings.

SBMLValidationError 

SBMLValidationError(result, message)

Bases: ValueError

Validation failed, with the immutable result available to the caller.

Keep the findings available without requiring another validation.

collect_construction_diagnostics 

collect_construction_diagnostics(*, strict=False)

Collect grouped findings in an isolated context, including nested calls.

The yielded scope exposes a diagnostics snapshot. Strictness controls implicit parameter creation; callers decide when to raise ConstructionError.

record_construction_diagnostic 

record_construction_diagnostic(
    code,
    message,
    *,
    severity="warning",
    example=None,
    count=1,
)

Record a finding if collection is active, grouping by code and cause.

allow_implicit_parameter 

allow_implicit_parameter(symbol, element)

Record an undeclared assignment target and apply the authoring policy.

check 

check(value, message)

Check the libsbml return value and log an error if something happened.

Parameters:

Name Type Description Default
value int | None

the return value of a libsbml call. None means libsbml returned a null value and is logged as an error. An integer is a libsbml return status code: LIBSBML_OPERATION_SUCCESS is fine, any other code is logged with the text libsbml has for it.

 required
message str

what was attempted, used to construct the error message

 required

Returns:

Type Description
bool

True if the call succeeded, False if an error was logged. The function
bool

neither raises nor exits, the caller decides what a failure means.

log_sbml_errors_for_doc 

log_sbml_errors_for_doc(doc)

Log errors of current SBMLDocument.

log_sbml_error 

log_sbml_error(error, index=None)

Log SBMLError.

error_string 

error_string(error, index=None)

Get string representation and severity of SBMLError.

validate_doc 

validate_doc(doc, options=None, title=None)

Validate SBMLDocument.

The error log of the document is cleared and restored during the validation, so an SBMLError proxy obtained from doc.getError() before the call is invalid afterwards; take a new one from the document (or use the snapshots of the result).

:param doc: SBMLDocument to check :param title: identifier or path for validation report :param options: validation options and settings.

:return: ValidationResult