Support time dependent changes in conditions

[matthiaskoenig]

Which problem would you like to address? Please describe.
I often have simulation experiments where I not only have to change initial values but also values after a certain time. I.e. the conditions do not only depend on initial changes but on time time-dependent changes.
E.g. clamping protocols where values are clamped over time to increasing values (e.g. t=0, D=0; t=10, D=1; t=20, D=2, ...). Also multiple dosing studies in pharmacokinetics with dosing applied multiple times (e.g. t=0 hr, D=100 mg; t=24 hr, D=100 mg; ..., with D being additional doses added in the system, e.g. tablets).

Describe the solution you would like
Extend condition definition to allow to specify the value to set and the corresponding time.

Describe alternatives you have considered
The suggested solution is always to encode such complex time-dependent protocols/conditions as events with multiple assignments. This has the downsides that

• protocols are hardcoded in the model (which results in a lot of overhead if many different protocols are applied to the model). In addition switching variables and piecewise functions have to be added to switch between multiple protocols.
• the information about changes to the model in the condition is hidden in event assignments instead of accessible via the condition table (basically only the switches are set in the condition table)
• events are poorly supported by software (many issues, missing support), so that the PETab and the model is less exchangeable (see e.g. Events with trigger that has an initial value of False are not supported AMICI-dev/AMICI#1760, Bug in handling events correctly with model changes sys-bio/roadrunner#983). It is very difficult to get events with full support correctly to work. For instance also no support for priorities in AMICI and so on. Not sure if adjoints are correct with events, ... Events also create simulation overhead.

Additional context
This issue has been discussed during some meetings already. It would be great if this could be supported in future PETab versions.

[dweindl]

Agreed that this would be important to finally address. Ideally in the next PEtab version.

Related issue: #16.

[dilpath]

This is currently being develop separately [1], and will hopefully be integrated into the next PEtab version.

Documentation is currently poor but there is a brief example [2] that involves the new "timecourse" TSV file [3] to specify the time points when new conditions begin.

The package supports integrating timecourses as:

• piecewise functions in SBML
• events in SBML
• a loop over simulations (currently only for AMICI)

These were all supported at some point but may not longer work as I have been developing the package to suit my needs. If you prefer something in particular and would like to start using this soon, let me know what you would like.

The current design in terms of PEtab files is that all conditions are in the normal conditions table, and then a sequence of them is specified in the timecourse table (e.g. [4], [3]) with some timecourse ID. This timecourse ID replaces condition IDs in the measurements table (e.g. [5]).

[1] https://github.com/dilpath/petab_timecourse
[2] https://github.com/dilpath/petab_timecourse/blob/218985be271bc394100bc21f4c3f7e62cd39d6fb/doc/examples/simple_timecourse.ipynb
[3] https://github.com/dilpath/petab_timecourse/blob/218985be271bc394100bc21f4c3f7e62cd39d6fb/doc/examples/input/simple_timecourse/timecourse.tsv
[4] https://github.com/dilpath/petab_timecourse/blob/218985be271bc394100bc21f4c3f7e62cd39d6fb/doc/examples/input/simple_timecourse/conditions.tsv
[5] https://github.com/dilpath/petab_timecourse/blob/218985be271bc394100bc21f4c3f7e62cd39d6fb/doc/examples/input/simple_timecourse/measurements.tsv

[dweindl]

See also #581