v2: Clarify condition table & initial assignments

[dweindl]

A question regarding the current v2 draft and how initial assignments interact with changes in the condition table:

PEtab/doc/v2/documentation_data_format.rst

Lines 274 to 305 in 4298e15

	1. **Evaluation of** ``targetValues``
	``targetValues`` are first evaluated using the *current* values of all
	variables in the respective expressions.
	* For the initial time period of an experiment, *current* values are
	determined by the initial conditions defined in the model.
	Constructs defining initial values of model entities (e.g., SBML's
	*initialAssignments*) are applied only once at the start of the first
	time period and are not re-evaluated in later time periods. The start
	time of the first time period is defined by the respective experiment.
	* For subsequent time periods, the *current* values are taken from the
	simulation results at the end of the preceding time period.
	2. **Assignment of the evaluated ``targetValues`` to their targets**
	All evaluated ``targetValues`` are simultaneously assigned to their
	respective targets. It is invalid to apply multiple assignments to the
	same target at the same time.
	* These assignments respect language specific interpretations of which
	variables are *atomic* or *derived*/*algebraic*. Most notably, SBML
	considers species amounts and compartment sizes but not
	concentrations to be *atomic*. This means that any entry that has a
	``targetId`` that refers to a species with
	``hasOnlySubstanceUnits=false`` will have its ``targetValue``
	(interpreted as concentration) converted to amounts using the
	**current** compartment size and then applied to the target's amount.
	For further details, refer to SBML semantic test suite case `01779
	<https://github.com/sbmlteam/sbml-test-suite/blob/7ab011efe471877987b5d6dcba8cc19a6ff71254/cases/semantic/01779/01779-model.m>`_.

If we have a model with a parameter p0 = 1 and another parameter p that is the target of an initial assignment p <- p0, and the experiment/condition tables specify some change p0 = 2 at time = 0 -- what is the value of p at time=0? 1 or 2?

According to the current draft, I would say the value should be 1, because the initialAssignment is evaluated before the condition-specific changes are applied.
This would be in line with how events triggering at t=0 would be handled in SBML, i.e. after the evaluation of initialAssignments. However, I am not sure if this is what users would expect. I think, in PEtab v1 this wasn't clearly specified, but implementations and users (and the test suite) assumed that changes through the condition table would be applied before evaluating initialAssignments (and thus, for the example above, the value of p would be 2).

How should this be handled? Generally, I'd find applying the condition table changes before evaluating initialAssignments more convenient. However, this is problematic if the targetValues themselves depend on targets of initialAssignments.

[dilpath]

In v1, if a species was assigned a value in the conditions table, this was assumed to override the initialAssignmentRule for that species, I think?

If a species ID is provided, it is interpreted as the initial condition of that species (as amount if hasOnlySubstanceUnits is set to True for the respective species, as concentration otherwise) and will override the initial condition given in the SBML model or given by a preequilibration condition. If NaN is provided for a condition, the result of the preequilibration (or initial condition from the SBML model, if no preequilibration is defined) is used.

This is at least true for AMICI: https://github.com/AMICI-dev/AMICI/blob/a87058e94831700fa18b8922e5ba33adb22fec91/python/sdist/amici/petab/sbml_import.py#L130-L135

If so, then overriding initialAssignmentRules for parameters would also make sense.

[dweindl]

In v1, if a species was assigned a value in the conditions table, this was assumed to override the initialAssignmentRule for that species, I think?

Right. This case is clear in v1 and nothing will change there. The problem is only overriding dependencies of initialAssignments (entities that appear in math elements of initialAssignments), not about targets of initialAssignments (their symbol attribute). (That initial assignments are used in AMICI to represent changes in initial concentrations are AMICI's problem - I would leave that out of this discussion.)

[dilpath]

Thanks, then I agree, it makes sense to move initialAssignmentRules to after condition changes. This means that if the user derived the analytical steady state expressions and specified them as initialAssignmentRules in the usual way, then the system still starts in steady state regardless of condition changes.

[dweindl]

After thinking a bit more about this issue: This is not specifically about initial assignments, but about model initialization in general. Initial assignments should not be treated different than any other value attributes of parameters or initialConcentration / initialAmounts. All SBML initialization should happen simultaneously. Accordingly, performing SBML initialization after applying PEtab changes only makes sense if SBML initialization is skipped for all PEtab-initialized entities (otherwise, the PEtab changes would have no effect).

In this case, the two most reasonable options to consider are:

A: PEtab changes are evaluated and applied before SBML initialization

• targetValue expressions that are part of the first period must not refer to any model entities since their values aren't defined yet
• For any model entity that occurs as targetId in the first period of a given experiment, SBML initialization is skipped. I.e., the respective parameter value, initial amount/concentration, initial assignment is ignored (or equivalently, overwritten by the PEtab targetValue).
• Only condition table changes after the first period could be directly represented by SBML events. (Condition table changes for the first period would be equivalent to initial assignments).
• This is (mostly?) how things were handled in PEtab v1, although not clearly specified. Some problems didn't exist back then, because the condition table changes were always number literals or parameters defined outside the model.

B: PEtab changes are evaluated and applied after SBML initialization

This is what the current v2 draft suggests.

• targetValue expressions may also refer to targets of initial assignments for the first period
• Any initial assignment will be evaluated based on what is specified in the model, ignoring any PEtab changes, which might be somewhat surprising.
• This way, all PEtab changes, including the start of the first period, could be directly represented as SBML event assignments.

Example

I'll try to illustrate the differences with this example:

model (SBML/antimony):

p1 = 1       # parameter.value 
p2 = 2 * p1  # initial assignment
p3 = 3 * p1  # initial assignment
p4 = 4       # parameter.value 

experiment table:

experimentId	time	conditionId
experiment1	0	condition1

condition table:

conditionId	targetId	targetValue
condition1	p1	2
condition1	p3	5
condition1	p4	p2

The resulting values at the start of experiment1 would be:

	p1	p2	p3	p4
A: PEtab init. applied SBML	2	4	5	(illegal change)
B: SBML init. applied before PEtab	2	2	5	2

---

Assuming that the model may encode some complex initialization based on a few potentially condition-specific key parameters, I think option A would be the most convenient and least surprising to PEtab v1 users.

[FFroehlich]

With the current spec for v2, I would be in favour of option B. It says

For the initial time period of an experiment, current values are determined by the initial conditions defined in the model.

after all. Or is there anything that can't be expressed that way?

[dweindl]

Yes, currently v2 would be pretty much B.

I think everything can be expressed either way, with more or less effort.

However, meanwhile I am not sure if B has sufficient (or any) advantages that would warrant breaking v1 behavior. (And at the time of writing #581, at least I was not aware that this would be so much of a change, requiring not only updating PEtab tables, but also often the models.)

[matthiaskoenig]

How this normally works is:

• all InitialAssignments are applied
• experiment/simulation/event specific changes are applied afterwards. I.e. the values are the values of the timecourse experiments given at time 0

This is how basically all simulators are doing this (e.g. COPASI, roadrunner)

[matthiaskoenig]

Similar issue with events in the model triggered at time=0. This should probably also be applied before the experiment changes. I.e. when creating the PETab time course events priorities should be added, so that the PETab assignments are applied after the events already existing at the model.

[FFroehlich]

However, meanwhile I am not sure if B has sufficient (or any) advantages that would warrant breaking v1 behavior. (And at the time of writing #581, at least I was not aware that this would be so much of a change, requiring not only updating PEtab tables, but also often the models.)

Why would we need to update models?

conditionId	targetId	targetValue
condition1	p1	2
condition1	p2	4
condition1	p3	5
condition1	p4	p2

would do the trick in the example above right?

I do see the disadvantage that this doesn't allow the usage of as much "infrastructure" in the model definition, but this really only an issue if the model is not actively being developed.

[matthiaskoenig]

We agreed that the assignments should work like events. It is clearly defined that InitialAssignments are applied when the model is loaded, i.e. this defines the initial state. Events are applied afterwards when a simulation is run. The only question for me is how the order is between events triggered by time in the model (which should be applied first) and PETab timecourse assignments happening at the same time.

[dweindl]

How this normally works is:

* all InitialAssignments are applied

* experiment/simulation/event specific changes are applied afterwards. I.e. the values are the values of the timecourse experiments given at time 0

This is how basically all simulators are doing this (e.g. COPASI, roadrunner)

Right. The question was mostly whether the changes encoded in the PEtab condition table are applied before or after the first step.

Similar issue with events in the model triggered at time=0. This should probably also be applied before the experiment changes.

I would find that very confusing, because for any later point, SBML events would be triggered/executed after applying the PEtab changes.

[dweindl]

Why would we need to update models?
[...]
I do see the disadvantage that this doesn't allow the usage of as much "infrastructure" in the model definition, but this really only an issue if the model is not actively being developed.

Okay, right, it's not strictly necessary to update the model, it's just that the initialization that previously could have been implemented through initialAssignments now needs to be added to the condition table.

[matthiaskoenig]

I would find that very confusing, because for any later point, SBML events would be triggered/executed after applying the PEtab changes.

Makes sense. I got confused. SBML events triggered after applying the PEtab changes of course.