Add Simulation Parameter tab to Compound Building Block

[sfrechen]

We have several compounds with "fixed" simulation parameters, e.g. blood to plasma concentration ratio, specific permeabilities. When loading the compound snapshot from the template libraries, the use is not aware of that. An in case the user is a aware of it, these parameters need to be updated manually in every simulation that will be created for the compound.

I propose to add a Simulation Parameters Tab:

This tab should provide a list that CAN be filled by the user by adding entries to rows, e.g. for a compound named CompoundName:

Path	Value	Value Origin
CompoundName|Blood/Plasma concentration ratio	0.66	Publication-Author et al. 001
Neighborhoods|Duodenum_int_Duodenum_cell|CompoundName|P (interstitial->intracellular)	0.1 cm/min	Parameter Identification-Fit XYZ
Neighborhoods|Duodenum_int_Duodenum_cell|CompoundName|P (intracellular->interstitial)	0.1 cm/min	Parameter Identification-Fit XYZ
Neighborhoods|UpperJejunum_int_UpperJejunum_cell|CompoundName|P (interstitial->intracellular)	0.1 cm/min	Parameter Identification-Fit XYZ
Neighborhoods|UpperJejunum_int_UpperJejunum_cell|CompoundName|P (interstitial->intracellular)	0.1 cm/min	Parameter Identification-Fit XYZ
Click for new entry...

The listed parameter should then override the calculated values when creating a simulation with this compound.

@Yuri05 @TWendl @Incei @JanSchlender @AndreDlm @PavelBal @StephanSchaller

[StephanSchaller]

Very much in support of this

[msevestre]

This raises so many questions.

• Are those parameters now readonly in the simulation? or can the user edit them?
• What happens if the user changes a parameter in the compound after it being used in the simulation ? Or update commit logic rely on parameters types but now we would update parameters with different types.. I just tried with ExpressionProfile and Individual and it is vey difficult to change this logic at this stage
• What happens if we rename the compound. Path should probably be updated?
• What happens if a parameter is not found?
• How will the user know how to create such a path? The one in neighborhood are very tricky for instance

The easy implementation: Overwrite and forget. in this case, (what is suggested) the amount of work is minimal. After this, this will become more complicated

[sfrechen]

• Are those parameters now readonly in the simulation? or can the user edit them?

They are transferred to the simulation but there they are treated as usual editable parameters as before.

• What happens if the user changes a parameter in the compound after it being used in the simulation ? Or update commit logic rely on parameters types but now we would update parameters with different types.. I just tried with ExpressionProfile and Individual and it is vey difficult to change this logic at this stage

PK-Sim has to treat such parameters as compound parameters with regard to commit and update. So, in case an update or commit is done, PK-Sim needs to check whether such parameters are defined in the compound.

• What happens if we rename the compound. Path should probably be updated?

Good point. Maybe one can work with MOLECULE (similar as in MoBi).

• What happens if a parameter is not found?

Give a warning. Similar as if we import populations with unknown parameter pathes.

• How will the user know how to create such a path? The one in neighborhood are very tricky for instance

Well, I think this feature is for rather advanced users anyway. Especially the initial set-up of it. We may give some guidance in the documentation on how to find pathes. Later, we may think about it to add a feature to copy a path as a text string (e.g. when right clicking on a parameter in a contex menu). Please be aware that currently ALL users have issues with such template models as they might not even be aware of such simulation parameters. And in case of forgetting them, the resultng model would be crap...

[msevestre]

This

PK-Sim has to treat such parameters as compound parameters with regard to commit and update. So, in case an update or commit is done, PK-Sim needs to check whether such parameters are defined in the compound.

Is going to be challenging. The rest is ok, provided that we do not want to support some extra worfklow to create a path from a model structure as we do in MoBi (which is horrible to use with the current implementation)

[Yuri05]

Good point. Maybe one can work with MOLECULE (similar as in MoBi).

Agree.

PK-Sim has to treat such parameters as compound parameters with regard to commit and update. So, in case an update or commit is done, PK-Sim needs to check whether such parameters are defined in the compound.

As Michael said, this would be not so easy and would include some use cases we did not have in PK-Sim so far at all. (e.g. adding parameters to a building block etc.). To simplify our life (but also to avoid some potential conflicts) I would suggest:

• do NOT provide update/commit functionality for the "Simulation parameters" defined in a compound building block
• allow adding/editing of "Simulation parameters" within a compound building block only as long as the compound is NOT used in any simulation

As @sfrechen mentioned, this is pretty advanced use case which will be very rarely used by the most users. Thus from my point of view the limitations in update/commit functionality are acceptable.

[Yuri05]

@sfrechen Can you please list all use cases of "compound=>simulation parameters overwriting" which have occurred so far? E.g. when looking at the qualification plans where this have been used, I saw just one use case: overwriting the mucosa permeability (interstitial<=>intracellular). Maybe we can solve this differently by reparameterization of our models (which I would definitely prefer).

Example of simulation parameters overwriting from CYP3A4-DDI Quali plan https://github.com/Open-Systems-Pharmacology/Qualification-DDI-CYP3A4/blob/cb76470cf79818e1c03967c7da37293f330f66c4/Qualification/Input/qualification_plan.json#L67-L266

[msevestre]

Also we need to add a dimension and a unit column unless we expect the user to know the internal unit of the parameter they want to override.

I think this feature is a massive break in the encapsulation that we have so far and I also would like to understand why this is required.

[StephanSchaller]

How will the user know how to create such a path? The one in neighborhood are very tricky for instance

I would not allow manual addition of parameters. The main need (use-case) as I understand it is to cross-commit these parameters to other simulations. So it should suffice to create these parameters in the BB through commit from Simulation.

Maybe this simplifies things?

[sfrechen]

@sfrechen Can you please list all use cases of "compound=>simulation parameters overwriting" which have occurred so far? E.g. when looking at the qualification plans where this have been used, I saw just one use case: overwriting the mucosa permeability (interstitial<=>intracellular). Maybe we can solve this differently by reparameterization of our models (which I would definitely prefer).

We have more. I remember for example Clarithromycin|P (blood cells->plasma) and Clarithromycin|P (plasma->blood cells) or for blood to plasma ratio (forgot the compound). We have also internal examples with other parameters which I do not know by heart....

Also we need to add a dimension and a unit column unless we expect the user to know the internal unit of the parameter they want to override.

Sure. See my example. I imagine a table similar to the "favourite" table.

I would not allow manual addition of parameters. The main need (use-case) as I understand it is to cross-commit these parameters to other simulations. So it should suffice to create these parameters in the BB through commit from Simulation.

I guess that makes things even more complicated...

[sfrechen]

And with regard to finding pathes: I think every advanced user also uses at some extent the toolboxes. Here, we do also work with pathes. I really do not see the issue. Our users are experts and know what they do. Getting the information whether there are potential simulation parameters is way less staright forward and the currentw orkflow of setting them manually is quite error-prone since they can easily be forgotten without any warning...

[StephanSchaller]

I guess that makes things even more complicated...

Why?

[sfrechen]

Why?

Michael and Juri indicated that commit and update is pretty complicated... And your suggestion is to commit it from simulations to building block. From a user perspective - I agree - this is a nice add-on feature to "automatically" fill the list.

[StephanSchaller]

• I agree - this is a nice add-on feature to "automatically" fill the list.

If we make it the ONLY way to fill the list is should simplify things. And this is also the usual workflow: Edit parameters in a simulation (either manually or through PI) and then trying to get them to other simulations. Adding them individually/manually on the BB level is not required (maybe deleting them from the list could be of interest).

[msevestre]

So it should suffice to create these parameters in the BB through commit from Simulation.

What building block are you talking about? The reason why those parameters are not defined in a BB is well, because they are not relying on one building block only. Why would I commit a parameter in a compound and not in an individual for instance if the parameter relies on parameters coming from individual AND compound.

I think we should think about this a bit more.

Sure. See my example. I imagine a table similar to the "favourite" table.

Yes but favorite relies on existing parameters so we know the dimension and units. If we only use path, this information is not available and therefor this needs to be input by the user.

Maybe this is another type of action to be used while creating a simulation. After Individual, compound, Events etc.. there is another step, which is Parameter Overwrite and this would allow the selection of another building block type that we do not have yet..

[Yuri05]

How about this:

• We identify all simulation parameters which have been "overwritten" by a compound so far

• In PK-Sim, for each of those parameters we define a new "overwrite" parameter in the compound building block with the default value NaN

  • Each "overwrite" parameter would be named following the same naming pattern, e.g. Overwrite Mucosa Duodenum Permeability (interstitial->intracellular) Overwrite Mucosa Duodenum Permeability (intracellular->interstitial) ... Overwrite Permeability (plasma->blood cells) Overwrite Permeability (blood cells->plasma) ...

  • Thus compounds would be extended with the list of parameters, which could be displayed within the new panel of the "Advanced Parameters"

    "Overwrite" parameters in compound

    

  • The formula of all corresponding parameters in the simulation is extended like this: OverwriteValue != NaN ? OverwriteValue : <Current Formula> Example:

    Parameter: Neighborhoods|Rectum_int_Rectum_cell|C1|P (intracellular->interstitial)
      Formula: OverwriteValue != NaN ? OverwriteValue : P * P_cell_int_factor * P_int_scalefactor
          P_cell_int_factor: Neighborhoods|Rectum_int_Rectum_cell|C1|P_cell_int_factor
          P_int_scalefactor: C1|Mucosa permeability scale factor (transcellular)
          P: C1|Permeability
          OverwriteValue: C1|Overwrite Mucosa Rectum Permeability (intracellular->interstitial)

This would allow to treat all those "overwrite" parameters in the same way as all other building block parameters in PK-Sim:

• Update/Commit possible without additional effort
• User does not need to deal with parameter paths
• Dimension/Unit/Range check/... are handled by PK-sim in the same way as for all other parameters

The main disadvantage is that those "Overwrite" parameters are defined by PK-Sim and not by user, thus every time when a new simulation parameter must be "overwritten": new software update is required. However I think this is not too often the case.

[msevestre]

Also we are creating a bunch of dummy parameters for nothing in all compound using this approach. I think it's the good direction but I don't like the static approach

[sfrechen]

We identify all simulation parameters which have been "overwritten" by a compound so far

Almost impossible. Will never bee comprehensive.

I don't like the static approach

Would also prefer a dynamic solution.

[Yuri05]

Well, then we need to define parameters by path (with all pros/cons discussed before).

In this case we should either invest some time into investigating how update/commit can be realized (and then decide if it is worth the effort of implementing it). Or we should really only allow ading/editing of simulation parameters in compound which is not used in any simulation (if we don't have update/commit and we allow editing of simulation parameters in used compounds - we will get inconsistencies, e.g. recreating a project from snapshot will create not the original parameterization).

Also I would require that the MOLECULEkeyword is mandatory for every added simulation parameter path (a compound may change only parameters which depend on the given compound!)