Time-dependent changes in component values

[dilpath]

related: #16 #540

If you are already familiar with this, you could skip straight to the "Feedback" section and share your thoughts.

A couple of (currently unofficial) PEtab extensions have been developed, to specify time-dependent changes in model components like parameters and state variables. An application example is a blood glucose model with intravenous infusion of glucose into a patient, where the rate of intravenous infusion might be manually adjusted by a nurse to control blood glucose levels. The intravenous infusion rate could be modeled as a time-dependent rate, which is fast or slow according to how the nurse chooses.

In terms of PEtab, this application example could be specified by first specifying two conditions (fast and slow), then specifying the timepoints when they are applied.

Table 1 Example PEtab condition table

conditionId	infusion_rate
fast_infusion	1.5
slow_infusion	0.5

Table 2 Example timecourse specification, in the current PEtab Timecourse format

timecourseId	timecourse
patient0	0:slow_infusion;20:fast_infusion;45:slow_infusion

This specifies that "patient0" receives a fast infusion in 20 <= time < 45, and a slow infusion otherwise.

Alternative implementations
There are currently two implementations of a specification format for these timecourses. An important difference is that the PumasQSP dosing table describes relative changes, whereas PEtab Timecourse specifies absolute changes.
PEtab Timecourse: https://github.com/dilpath/petab_timecourse/
Pumas QSP dosing table: https://help.juliahub.com/pumasqsp/dev/tutorials/petabimport/#dosing_table

The PEtab Timecourse format is shown in Table 2.
The Pumas QSP format extension has a "dosing" table, which augments the standard PEtab condition table, just like the PEtab Timecourse table above.
Table 3 Example timecourse, as a PumasQSP dosing table

conditionId	speciesId	value	time	isRate
slow_infusion	infusion_rate	1	20	0

i.e., here "infusion_rate" is modeled as a species, and the fast infusion rate is modeled as a relative change of the default "slow_infusion" condition. i.e., "infusion_rate" at t=20 is "infusion_rate + 1" => "0.5 + 1" => "1.5", which matches the fast infusion rate in Table 1. After 25 time units, the relative change is reverted back to the value prior to "t=20", i.e. 0.5.

Further alternatives
After discussing with @paulflang @dweindl and others, there are a few more alternatives.

Alternative dosing table
This replaces both the condition table (Table 1) and dosing table (Table 3), with a single combined table.
Table 4

conditionId	componentId	value	time	isRate	relative
patient0	infusion_rate	0.5	0	0
patient0	infusion_rate	1	20	0	1

Here, the relative change from the previous dosing table is now explicitly specified.

Alternative timecourse table
This replaces the PEtab Timecourse (Table 2), to support relative changes.
Table 5

timecourseId	conditionId	time	relative
patient0	slow_infusion	0
patient0	fast_infusion	20
patient0	slow_infusion	45

Alternative condition table
This replaces Table 1, to support relative changes. This can be paired with Table 2 or Table 5 (without the "relative" column).
Table 6

conditionId	infusion_rate
fast_infusion	infusion_rate + 1
slow_infusion	0.5

New measurement table
The measurements table would be changed to now use timecourses. e.g., to specify pre-equilibration with condition "slow_infusion", then simulation with condition "fast_infusion" for 20 time units:
Table 7 Measurements example: condition table in the Table 1 format

conditionId	infusion_rate
fast_infusion	1.5
slow_infusion	0.5

Table 8 Measurements example: timecourse table in the Table 2 format

timecourseId	timecourse
patient0	inf:slow_infusion;0:fast_infusion;20:slow_infusion

The measurements table would then look like the following, where preequilibrationConditionId and simulationConditionId have been replaced with timecourseId. For simplicity, we can support conditionIds in the timecourseId, for timecourses that only involve a single condition ID.
Table 9 Measurements example: new measurement table

observableId	timecourseId	measurement	time
observed_blood_glucose	patient0	...	...

Feedback
At this point, it would be great if we could firstly agree on the scope of this work.

1. Are you in favor of timecourse specification -- i.e., instantaneous changes in parameter or species values, at specified timepoints?
   1.1. Are you in favour of specifying the duration of changes explicitly? e.g. Tables 3 and 4
   1.2. Are you in favour of being able to specify modifications of the species' ODE, rather than the species directly? e.g. Tables 3 and 4 have "isRate". e.g. given a "relative" change: if "isRate" is "1", then the "value" gets added to the species ODE RHS. If "isRate" is "0", then the "value" gets added to the species itself.
2. Are you in favor of specifying relative changes in components?
   2.1. Are you in favor of arbitrary expressions in the conditions table? e.g. Table 6
3. Which of the changes would you be OK with including in core PEtab, and which would you prefer in an official extension?

After getting some consensus on the scope, I would then ask for feedback on specific format alternatives.

[dilpath]

1. Are you in favor of timecourse specification -- i.e., instantaneous changes in parameter or species values, at specified timepoints?

Yes, it would help with a few modeling projects I am involved in.

1.1. Are you in favour of specifying the duration of changes explicitly? e.g. Tables 3 and 4

No, it is already covered by being able to specify the start time of the next condition.

2. Are you in favor of specifying relative changes in components?

Yes.

2.1. Are you in favor of arbitrary expressions in the conditions table? e.g. Table 6

Yes.

3. Which of the changes would you be OK with including in core PEtab, and which would you prefer in an official extension?

I would include all changes in core PEtab. Developers can simply choose to not support the new features, e.g. relative changes or timecourses that are more complicated that preequilibration+simulation conditions, if desired.

[dilpath]

@PEtab-dev/petab-editors

[paulflang]

Thanks for starting this discussion here, @dilpath. Thinking again of table 4, I think duration should not be interpreted as stop time or similar. Perhaps it should be replaced with isRate instead. 0 would indicate it is instantaneous (i.e. a Bolus dose) and 1 that it is a rate (i.e. an infusion). Why not simply add a parameter that describes the rate to the model instead of using an isRate column? Because I think the dosing/perturbation/condition model should be independent of the biological model in a similar way the noise and observation models are independent of the biological model. This facilitates modularity/reusability. Is there any chance you could edit table 4 and comment 1.1 accordingly?

A question that remains is what to do with preequilibration conditions. Imo these could be like any other conditions, but with time set to -Inf (no preequilibration column would be needed in the measurement table anymore (I was always wondering why it was possible to chain 2 conditions together, but not multiple -> if all (atomic) disturbances are represented in sth like table 4, and bundled together with conditionIds like in the measurement table, than this question becomes obsolete anyway)).

Additionally, I would like to argue that whatever format is used, it should adhere to the tidy data principles, unless there is a good reason not to.

Let me also respond to your questions:

1. Are you in favor of timecourse specification -- i.e., instantaneous changes in parameter or species values, at specified timepoints?

Yes, with isRate 0. But with isRate 1 it should be non-instantaneous.

1.1. Are you in favour of specifying the duration of changes explicitly? e.g. Tables 3 and 4.
No, I am no longer in favour of that.

1.2 Are you in favour of being able to specify modifications of the species' ODE, rather than the species directly?

I think both should be possible. Modifications to species (bolus doses) and ODEs (infusion doses).

2. Are you in favor of specifying relative changes in components?

Yes, there are many cases where you know the amount of a substance in a pill or the rate at which an infusion adds a substance to the body, but you don't know the current amount in the body of the patient when they swallow that pill.

2.1 Are you in favor of arbitrary expressions in the conditions table? e.g. Table 6.

No, I think only two things should be allowed: Floats and Strings (i.e. parameterIds). These parameterIds should be set in the parameter table with estimate equals 0 or 1. If arbitrary expressions were allowed, then you would lose the ability to set estimate to 1.

3 Which of the changes would you be OK with including in core PEtab, and which would you prefer in an official extension?

No strong preferences here.

[dweindl]

Thanks for pushing that again.

1. Are you in favor of timecourse specification -- i.e., instantaneous changes in parameter or species values, at specified timepoints?

Absolutely.

1.1. Are you in favour of specifying the duration of changes explicitly? e.g. Tables 3 and 4

No. (It sounds like this point became obsolete anyways.)

2. Are you in favor of specifying relative changes in components?

Yes, both absolute and relative would ideally be possible.

2.1. Are you in favor of arbitrary expressions in the conditions table? e.g. Table 6

No strong opinion (yet).

3. Which of the changes would you be OK with including in core PEtab, and which would you prefer in an official extension?

I'd like to see it as part of core PEtab, replacing the current preequilibrationConditionId+simulationConditionId (while keeping that functionality, of course).

[dilpath]

Thanks for the feedback already! Especially the "duration" correction. For now, I made the "duration" -> "isRate" change in Tables 3 and 4, and added Feedback item 1.2.

1.2. Are you in favour of being able to specify modifications of the species' ODE, rather than the species directly? e.g. Tables 3 and 4 have "isRate". e.g. given a "relative" change: if "isRate" is "1", then the "value" gets added to the species ODE RHS. If "isRate" is "0", then the "value" gets added to the species itself.

Yes, it has use cases, e.g. the infusion rate in the examples above could be modeled with a species directly, instead of indirectly via the "infusion_rate" component.

I think there are a few interpretations of this (e.g., is the rate the value itself, or the value divided by the timecourse period duration? do we accumulate changes over timecourse periods, or reset them after each timecourse period?). We could discuss them after deciding whether to have this in the spec.

[dweindl]

See also #581