Forums

Hello Sarah,

I am not sure that the proposed solution is sufficient. Even in future
releases of SBML being it levels or versions. The semantics of each
element in the document is specified by the default name space of the
containing document. Starting with this premises I think that it must
be impossible to create any SBML object without referencing the
document.

This of course would lead to an API change which is very similar to
yours however instead of specifying level and version we need to
provide a pointer to the document.

This would change the code for example 3 to:

SBMLDocument * pD = new SBMLDocument(int Level = 2, int Version = 3);
Compartment * pC = new Compartment(pD);
Model * pM = new Model(pD);
pM->addCompartment(pC);

which would succeed. However the following would fail
SBMLDocument * pD23 = new SBMLDocument(int Level = 2, int Version = 3);
Compartment * pC = new Compartment(pD23);
SBMLDocument * pD12 = new SBMLDocument(int Level = 1, int Version = 2);
Model * pM = new Model(pD12);
pM->addCompartment(pC);

We can discuss whether it is necessary to have to add the model
explicitly or whether the above used constructor suffices. I prefer to
have to explicitly add each object.

Please note that I think the following should fail to even though the
name space of the documents are the same:
SBMLDocument * pD23 = new SBMLDocument(int Level = 2, int Version = 3);
Compartment * pC = new Compartment(pD23);
SBMLDocument * pD12 = new SBMLDocument(int Level = 2, int Version = 3);
Model * pM = new Model(pD12); pM->addCompartment(pC);
pM->addCompartment(pC);

The reason why it should fail is that the compartment might be
perfectly specified in document pD23 however invalid in document pD12
because of missing unit definitions.

This leads to an additional requirement or API. One needs to be able to
explicitly change the document for each object. This document change
would convert the object if needed including all kinds of error
messages and warnings. This automatically prevents situations you
handle in point 4.

I have not addressed one of the issues you have brought up and that is
how do we deal with additional packages and the extensions needed for
libsbml, e.g. how do we create a compartment which has additional
attributes or allows additional child elements. I actually think that
the compartment itself should still be created in the SBML document.
Additional attributes need to be set with SBML extension for the
attributes name space. The same is true for additional child elements
which do not exist in the SBML name space. New elements specific to the
additional packages are of course added with methods provided by the
libsbml extension.

Thanks,
Stefan


On Tue, 16 Sep 2008 11:58:54 -0700
Sarah Keating <skeating@caltech.edu> wrote:

> ATTENTION:
> A situation has arisen where it may be necessary to alter the existing
> libSBML API and we would appreciate your comments and feedback
> regarding this.
>
> We especially want people's input on the important question near the
> end of this message.
>
>
>
> I know it's hard to believe but libSBML has a problem that has
> presented itself in several ways :-) . Namely, it is possible to
> create in-memory SBML object structures that are not actually valid
> SBML. It also possible to "lose" attributes when you write out a
> document. A detailed example of this is given here:
>
> http://sbml.org/SBML_Projects/libSBML/Modularization#createSBML
>
> Another example would be the case where a 2D Compartment is created
> and then added to a model within a L1V2 document. Writing out the
> document would seem fine as the spatialDimensions attribute is not
> present in L1V2 and therefore not written out. However, software
> creating such a model and then querying the compartment would get the
> following:
>
> Level of Compartment: 1
> SpatialDimensions of Compartment: 2
>
> - which is not valid SBML.
>
> We need to fix this - as Level 3 modules will only create further
> problems of a similar nature :-)
>
>
> Our proposed solution is
>
> 1) additional constructors for each object - taking level, version and
> xml namespaces as arguments
>
> e.g.
> Compartment (unsigned int level, unsigned int version,
> XMLNamespaces* xmlns = 0);
>
> 2) the setter functions for each object do not create invalid sbml
>
> e.g.
>
> compartment->setUnits("volt")
>
> would have no effect on the units variable for the compartment
>
> 3) the add functions for adding components to models do not add an
> object if there is a mismatch between the level/version/xmlns
>
> e.g.
>
> Compartment *c = new Compartment(1, 2);
> Model * m = new Model(2, 3);
> m->addCompartment(c);
>
> would not add the compartment to the model
>
> 4) there is an additional validation function checkInternalConsistency
> that runs a validator that specifically looks for mismatches between
> levels/versions and attribute values
>
> eg this would log an error for a compartment within an L1V2 model that
> had spatialDimensions set to 2.
>
> =====
>
> Item 1 will happen - as it will be useful, and possibly necessary, for
> modularization wrt level 3 extensions
>
> Item 4 we think would be a useful addition to the libSBML API as the
> existing validation focusses on the level and version of the document
> being validated and does not specifically look at the internal
> representation of each object.
>
> However, we would appreciate feedback on the best approach to items 2
> and 3.
>
> We think it is most useful that if a set/add function fails that this
> is reported to the user in some fashion. However, using exceptions is
> problematic because of the need to support multiple programming
> languages. There are 3 possible solutions:
>
> A) Do nothing.
>
> The code that allows a user to set an invalid value or add an object
> with a mismatched level/version remains as it is currently.
>
> BUT ...
>
> we seriously encourage users to validate their internal
> respresentation using the new checkInternalConsistency function.
>
> B) No API change but set/add functionality altered
>
> The existing API remains the same.
>
> However, each SBase object has a flag mModificationFailed and a
> function to return the value of this flag. The set/add functions
> reinitialize this flag to false and then check the validity of the
> function to be preformed. If the value being set is valid this is
> done, if setting the value would produce invalid SBML then no change
> is made to the internal value and the mModificationFailed flag is set
> to true.
>
> e.g.
> mModificationFailed = false;
> if (value >= 0 && value <= 3)
> spatialDimensions = value;
> else
> mModificationFailed = true;
>
> A user could then query this flag following a set/add function to
> determine whether the action was performed.
>
> c->setSpatialDimension(4);
> if ( c->modificationFailed() )
> {
> cerr << "Tried to set an invalid value in
> Compartment::setSpatialDImension\n";
> }
>
> C) API and functionality change
>
> All set/add functions currently return 'void'. The new API would
> change the return type of all these functions to 'bool'.
>
> e.g.
>
> void setSpatialDimensions(int value);
>
> would become
>
> bool setSpatialDimensions(int value);
>
> The code within the function becomes
>
> if (value >= 0 && value <= 3)
> {
> spatialDimensions = value;
> return true;
> }
> else
> {
> return false;
> }
>
> and to check the status
>
> if ( c->setSpatialDimension(4))
> {
> cerr << "Tried to set an invalid value in
> Compartment::setSpatialDImension\n";
> }
>
> ====
>
> There are obvious advantages and disadvantages to each of the above
> solutions. Although solution A obviously requires the least work from
> anyone, ourselves included, it does leave the issue outstanding.
> Solution B should not impact anyone's existing code but the continued
> reinitialization of the flag means that code checking this flag would
> need to be extremely careful. Solution C does involve an API change;
> but is consistent with the setLevelAndVersion function already within
> libSBML.
>
> We would be very grateful for any comments on the above.
>
> Sarah, Akiya & Mike
> ____________________________________________________________
> To manage your libsbml-development list subscription, visit
> https://utils.its.caltech.edu/mailman/listinfo/libsbml-development
>
> For a web interface to the libsbml-development mailing list, visit
> http://sbml.org/Forums/
>
> For questions or feedback about the libsbml-development list,
> contact sbml-team@caltech.edu
>


--
Stefan Hoops, Ph.D.
Senior Project Associate
Virginia Bioinformatics Institute - 0477
Virginia Tech
Bioinformatics Facility I
Blacksburg, Va 24061, USA

Phone: (540) 231-1799
Fax: (540) 231-2606
Email: shoops@vbi.vt.edu
____________________________________________________________
To manage your libsbml-development list subscription, visit
https://utils.its.caltech.edu/mailman/listinfo/libsbml-development

For a web interface to the libsbml-development mailing list, visit
http://sbml.org/Forums/

For questions or feedback about the libsbml-development list,
contact sbml-team@caltech.edu