Dimensional checking in Simbiology

I am installing the gPKPDtoolbox as described in the reference below. I'm trying to run an example from the examples that download with the toolbox from the MathWorks site.

Hosseini, I., Gajjala, A., Yadav, D.B., Sukumaran, S., Ramanujan, S., Paxson, R., and Gadkar, K. (2018). gPKPDSim: a SimBiology®-based GUI application for PKPD modeling in drug development. J. Pharmacokinet. Pharmacodyn. 1–17.

The example case is called IDR-2compPK, and is included in an sbproj file. The example cannot be simulated as supplied, at least in my setup (2017b, ml, simbio, opt, global opt, stats, parallel).

1) The model uses a non-standard unit, "fraction". The workaround is to add the unit fraction, or to change this to "dimensionless".

2) The model throws an error regarding two reaction rates. The two errors are similar, so I'll list one: Reaction rate dimension for reaction '[CentralAmt(mcg/kg)] - [PeriAmt(mcg/kg)]' must be either concentration/time or substance/time. Dimension substance/time is assumed. As you can see, the modeler put the units in the title of the species block. The actual units in the model are blank! I suspect that this is because:

3) If you try to put the units used (microgram/kilogram, that is micrograms substance/kilogram of body weight), you get an error: Invalid InitialAmountsUnits for species. Valid quantity types are amount, mass, and concentration. Clearly, the actual units desired for the model (mcg/kg) can't be used. I view this as an unreasonable constraint in a modeling package. The user should be trusted to set units that make sense. Doubly important because

4) This also precludes things like AUC. I get the same error if I try to create a species with units microgram*day/milliliter.

5) The units conversion tab is not set. The tic boxes in simulation settings (for dimensional analysis and units conversion) are not set. The errors appear whether the default units dimension is amount or concentration.

6) Earlier units discussions in this forum reference deprecated GUI functions. The solutions that folks have proposed earlier can't work because the UI they reference don't exist in 2017b.

I'd appreciate knowing 1) what settings the original authors used to get this model to run, and 2) whether or not I can turn off this dimensional checking so that I can run mass specific (per kg) simulations.

Also, it would be nice to be able to create species with ANY dimensions (that is, it would be cool to be able to check a box in the species dialog box that says "ignore dimensions for this species" to turn off dimensional analysis.

Answer 1

[Rick Paxson]

Hi,

I am sorry you have having trouble running these examples. Let me try to help and maybe you can answer some questions for me to help diagnose.

1. Adding a unit named "fraction" would work as will replacing it with dimensionless. However, the units defined by these models are added automatically by opening the examples in the gPKPDSim App. For example, running gPKPDSim and opening casestudy1_TwoCompPK_final.mat found in the userpath/Add-Ons/Toolboxes/gPKPDSimToolbox/code/Supp Info - 2nd Submission/1) Case Study 1 folder adds the required units. Note userpath denotes the path returned by the userpath command in MATLAB. Note that once added these units will persist from one MATLAB session to the next.

2. The Reaction rate messages are not errors but rather warnings. These are reminding a modeler that SimBiology, given no unit information, will assume the rate is in substance/time.

3. The limitation that SimBiology imposes on Species dimensions (i.e. amounts or concentrations) is too constraining and it will be relaxed in a future version. In the meantime it is possible to define state variables using Parameters with their Constant property set to false. This allows Parameters to vary as a function of time and of course can have any units. But note that this is not necessary to run the gPKPDSim examples, I an only providing this information to answer the general question and offer a workaround.

6. Could you point me to the deprecated GUI functions that you reference?

Lastly, could you confirm that the gPKPDSim examples run if opened from the app (not SimBiology)? The gPKPDSim App is performing further configuration on the models contained in the related sbproj file, e.g. applying doses.

I hope this helps to explain some of the problems you are having. Please let me know if you have more questions.

Answer 2

[Jim Bosley]

Ricardo,

Thanks for your prompt reply. In order:

1)Opening the model in gPKPDsim did indeed allow the simulation. I guess my learning path is different: I tried to open and use and understand the sbproj model in SB first. Running the model in the app does throw the same warning in the ML command window: Warning: Reported from Dimensional Analysis: Reaction rate dimension for reaction '[CentralAmt(mcg/kg)] - [PeriAmt(mcg/kg)]' must be either concentration/time or substance/time. Dimension substance/time is assumed. > In sbioaccelerate (line 71) In PKPD.Analysis/runPopulation (line 60) In PKPD.Analysis/run (line 43) In PKPDViewer.AnalysisApp/onRunAnalysis (line 1166) In PKPDViewer.AnalysisApp/create>@(h,e)onRunAnalysis(app)

2)Per 1, above, the reaction rate message may be moot. I think that the default dose is not set in the model per se, so the simualation task initially just gave all zero values. When I got the warnings, and the zero values (which I didn't see: they were in the mud at the bottom of the graph) I assumed it was broken. The sims, when run in the toolbox, did give good values. This does bring to mind a possible improvement in graphs (any graphs). There could be a margin around the graph axes. In this way, zero traces on the x axis would be visible and apparent.

3. Thanks for the update on the dimensional constraints. For parameters, your workaround will be used. For species, I will mislabel the units for now.

6. I note that your software has been around for a while - I remember us talking about what the ideal simulation package would include when you first started implementing it. In any case, some of the things that were in earlier packages are not there or are relocated. And so a lot of the videos and forum answers no longer apply. I think the point in my note was sparked by this exchange on the forum: https://www.mathworks.com/matlabcentral/answers/4706-unit-conversion-in-simbiology

Your note did indeed help solve my problems! Many thanks!

One thing came up in running the app. Can I show data on the same graph that shows the percentile ranges? I have to generate some data and put it in a file for example 3 and will check this, but if I can't then it will save me time to know.

Best,

Jim