Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Time-dependent changes in component values #564

Open
dilpath opened this issue Jun 27, 2023 · 6 comments
Open

Time-dependent changes in component values #564

dilpath opened this issue Jun 27, 2023 · 6 comments
Milestone

Comments

@dilpath
Copy link
Member

dilpath commented Jun 27, 2023

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
Copy link
Member Author

dilpath commented Jun 27, 2023

  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.

  1. 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.

  1. 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
Copy link
Member Author

dilpath commented Jun 27, 2023

@PEtab-dev/petab-editors

@paulflang
Copy link
Contributor

paulflang commented Jun 27, 2023

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).

  1. 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
Copy link
Member

dweindl commented Jun 27, 2023

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.)

  1. 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).

  1. 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
Copy link
Member Author

dilpath commented Jun 27, 2023

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
Copy link
Member

dweindl commented May 23, 2024

See also #581

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

No branches or pull requests

3 participants