Meaning of `Xref` in case 974

[paulflang]

I have a question on case 974: Xref is assigned to multiple variables. But what determines the value of Xref?

[luciansmith]

The mathematical meaning of a SpeciesReference is its stoichiometry, so it's the 'stoichiometry' attribute. It's analogous to the 'size' attribute of a compartment, or the 'value' attribute of a Parameter.

Like compartments/parameters/etc., any initial assignment or assignment rule will override that 'stoichiometry' attribute (if present). There aren't any in 974, but there should be in other tests.

If there's anything in the documentation or the SBML specs that led you astray in your thinking about this, let us know! The concept of giving a species reference an id with the mathematical meaning of 'the stoichiometry' was introduced in SBML L3, so it's possible that some of the language about it still needs to be updated.

[paulflang]

OK. Perhaps I can best express my confusion by asking the following questions.

So the stoichiometry of X in reaction J0 is 1, but overridden with Xref. But what is Xref, 1, 2, 3, ...? (My attempt to answer this would be: 1 is not overridden with Xref. Instead Xref is a handle to 1. The handle could be used to override 1 with a value from an initialAssignment or an assigmentRule, but this does not happen in the present model.)

Similarly I could ask: The value of parameter Z is 0, but it is set to Xref by an assignmentRule. But what is Xref, 1, 2, 3, ...?

[luciansmith]

I think I see your confusion! You wrote:

So the stoichiometry of X in reaction J0 is 1, but overridden with Xref.

This isn't true! The stoichiometry of X in reaction J0 is 1, and given the ID 'Xref'. So, essentially, your subsequent attempt to answer your own question is correct: 'Xref' is a handle to the stoichiometry; nothing is overridden.

<speciesReference id="Xref" species="X" stoichiometry="1" constant="false"/>

The 'speciesReference' itself has a stoichiometry of 1, and an id of 'Xref'.

A speciesReference is, in SBML L3, one of five fundamental elements with mathematical meaning, all of which have different default ways of setting their initial values:

• Species (initialValue or initialConcentration)
• Parameter (value)
• Reaction (mathematical value of child KineticLaw; cannot be set otherwise)
• Compartment (size)
• SpeciesReference (stoichiometry)

Does that help?

[luciansmith]

Here's another way to explain it. In once place in the model, we define a parameter Z with a value of 0:

      <parameter id="Z" value="0" constant="false"/>

And in another part of the model we define the speciesReference Xref with a value of 1:

          <speciesReference id="Xref" species="X" stoichiometry="1" constant="false"/>

And elsewhere, we have an assignment rule that overrides the value of Z with the value of Xref:

      <assignmentRule variable="Z">
        <math xmlns="http://www.w3.org/1998/Math/MathML">
          <ci> Xref </ci>
        </math>
      </assignmentRule>

However, we could have done the reverse: override the value of Xref with the value of Z:

      <assignmentRule variable="Xref">
        <math xmlns="http://www.w3.org/1998/Math/MathML">
          <ci> Z </ci>
        </math>
      </assignmentRule>

In the latter case, Xref would now be 0, meaning that the stoichiometry of the reaction was zero, and the reaction would effectively be dropped from the model.

[paulflang]

OK, I understand now. Probably I found using a stoichiometry in an assignmentRule so counterintuitive that I did not get it at first. Perhaps worth considering to put your explanation and examples somewhere in the documentation (ideally using Xref literally in an example, as it provides some way to Ctrl+F for it when this test suite case fails).

Also, I assume there is no way that libSBML does these substitutions for us/flattens the model, right? (If not: @giordano and @exaexa, then we should think about integrating that in SBML.jl.)

[luciansmith]

Great! I'll watch for ways to put this in the docs; perhaps in the .m files in the test suite itself.

I'm not sure what you mean by 'does these substitutions'. Do you mean a system where any use of Xref is replaced by a new parameter Xrefref, so only parameters are referenced in math, not speciesReferences?

[exaexa]

@paulflang re SBML.jl -- I see we don't really import the IDs (nor constness) of the SpeciesReferences so this can't work very easily. That can be fixed I'd say.

[paulflang]

That can be fixed I'd say. @exaexa : did you mean "That cannot be fixed"?

@luciansmith : I mean there are ConversionProperties options like "promoteLocalParameters", "expandFunctionDefinitions", "expandInitialAssignments" in libSBML. So I was wondering if there is something like "promoteStoichiometryIds", such that there is a global parameter Xref (or maybe reaction_id_Xref). Or maybe sth that converts this

      <assignmentRule variable="Z">
        <math xmlns="http://www.w3.org/1998/Math/MathML">
          <ci> Xref </ci>
        </math>
      </assignmentRule>
    </listOfRules>
    <listOfReactions>
      <reaction id="J0" reversible="true">
        <listOfProducts>
          <speciesReference id="Xref" species="X" stoichiometry="1" constant="false"/>
        </listOfProducts>

to this

      <assignmentRule variable="Z">
        <math xmlns="http://www.w3.org/1998/Math/MathML">
          <cn> 1</cn>
        </math>
      </assignmentRule>
    </listOfRules>
    <listOfReactions>
      <reaction id="J0" reversible="true">
        <listOfProducts>
          <speciesReference id="Xref" species="X" stoichiometry="1" constant="false"/>
        </listOfProducts>

when calling SBMLDocument.Convert() (not necessarily in the SBMLDocument itself, but in the Objects that represent it in libSBML).

[exaexa]

@exaexa : did you mean "That cannot be fixed"?

I meant just fixing the import of the IDs and constatnesses of the species references. The semantics is completely out of SBML.jl. :]

[luciansmith]

@paulflang : OK, I can imagine such a converter, that would convert any initial assignments to a double and just assign that to the 'stoichiometry' attribute, and (as you note) convert any use of Xref into use of it's stoichiometry value instead.

However, that wouldn't cover all the use cases; you'd still be left with Xref's being assigned a value in an assignment rule (or algebraic rule), or assigned a rate of change with a rate rule. But it could allow access to a greater variety of models for simulators that otherwise couldn't deal with speciesReference IDs.

[luciansmith]

Just filed https://github.com/sbmlteam/libsbml/issues/249 as a translation request; feel free to comment there if you have further requests or just more input. Thanks!