open-systems-pharmacology/docs

Open Systems Pharmacology - Live Documentation

About this Manual

This manual describes the Open Systems Pharmacology Suite. It includes a technical description of each software element with examples and references for further reading. The aim of the manual is to assist users in effectively developing PBPK models.

The handbook is divided into the following parts:

Mechanistic Modeling of Pharmacokinetics and Dynamics

"Mechanistic Modeling of Pharmacokinetics and Dynamics" provides a brief general introduction to the science of computational systems biology with a strong focus on mechanistic modeling of pharmacokinetics and –dynamics.

Go to: Mechanistic Modeling of Pharmacokinetics and Dynamics

Open Systems Pharmacology Suite

"Open Systems Pharmacology Suite" provides a brief overview of our software platform, its scope, and puts it into context with the science.

Go to: Open Systems Pharmacology Suite

Working with PK-Sim®

A technical description of the different software elements is presented starting with PK-Sim® focusing on physiologically-based pharmacokinetics in "Working with PK-Sim®".

Go to: Working with PK-Sim®

Working with MoBi®

MoBi® focusing on model customization and extension as well as on pharmacodynamics in "Working with MoBi®".

Go to: Working with MoBi®‌

Shared Tools and Example Workflows

Tools shared between PK-Sim® and MoBi® and some workflow examples are presented in "Shared Tools and Example Workflows".

Go to: Shared Tools and Example Workflows

Working with R

The interfaces to the common computing environment R is described in "Working with R".

Go to: Working with R

docs's Issues

pdf: Caption of sensitivity analysis chapter not properly displayed

Add appveyor script to generate pdf on the fly

Broken reference

Link to CVODE online doku in this section is broken.
Replace with e.g. https://computation.llnl.gov/projects/sundials/sundials-software

(Better) explanation of Update<=>Commit in MoBi

Here: https://docs.open-systems-pharmacology.org/working-with-mobi-r/mobi-r-documentation/setting-up-simulation#update-and-commit-changes-between-simulations-and-building-blocks

Feature wish: expand manual for explanation how to include additional clearance in Mechanism based inhibition

Original entry from @tobiasK2001
add Sebastians and Stephans explanations to manual: Open-Systems-Pharmacology/Forum#226 (comment)

see Open-Systems-Pharmacology/PK-Sim#950

Describe "user defined parameters"

Describe "user defined parameters" feature (introduced in 7.3)

Update enzyme ontogeny description

In https://docs.open-systems-pharmacology.org/working-with-pk-sim-r/pk-sim-r-documentation/pk-sim-expression-data#settings-in-the-protein-expression-tab

Current statement is wrong, because we have also ontogenie data in the intestine.

Currently, ontogeny information is only available for the liver and restricted to
a selection of important cytochromes ...

It could/should also be explained in more detail, how liver and intestine ontogeny values are used in a model.

Describe Fixed parameters in PI

Describe fixing parameter values during parameter identification (introduced in 7.2)

Improved documentation of quantile methods

I suggest to document how the individual numbers shown in the tooltip ( Open-Systems-Pharmacology/PK-Sim#124 ) are selected by the so-called nearest rank method. Furthermore, I would recommend to improve the documentation within the source code and the manual, to describe the quantile method used for the box whisker plots and potentially other parts of the code.

The standard reference is "Sample quantiles in statistical packages" by Hyndman et al (1996). Furthermore, a quick overview is given by https://en.wikipedia.org/wiki/Quantile where all methods from the paper are explicitly listed.

Using the paper notation (and "type=" Argument in R): OSP, R (by default, others supported), Excel (old PERCENTILE) use Definition 7; in comparison: Matlab uses Definition 5, Excel (new PERCENTILE.EXC) uses Definition 6 and SAS uses Definition 2 (by default, others supported).

Broken reference

Broken reference in this paragraph
Further details on modeling absorption in PK- Sim® are described in ???.

Missing captions in pdf

more missing captions (look for # in pdf):

• Page 9: Modeling Concepts - PD and Reaction Network Modeling
• Page 20: PK-Sim Projects
• Page 39: PK-SIM Expression Data
• Page 58: PK-Sim Compounds: Definition and Work Flows
• Page 85: PK-Sim® - Administration Protocols
• Page 90: PK-Sim® Events
• Page 93: PK-Sim® Formulations
• Page 220: MoBi® Tools
• Page 224: Shared Tools - Features of Tables
• Page 227: Shared Tools - Chart Component
• Page 266: Shared Tools - Sensitivity Analysis
• Page 273: Shared Tools - Import and Edit of Observed Data
• Page 281: Shared Tools - Default, Display and Base Units
• Page 283: Shared Tools - Reporting
• Page 285: Shared Tools - Working Journal
• Page 293: Shared Tools - History Manager and History Reporting
• Page 295: Workflow - Setting Up a Reaction Network
• Page 311: R - Introduction

Broken reference

In the Reaction kinetics section:
If you want to use relative paths (compare ??? for a discussion of the rationale behind the paths),

GitBook rendering problem: image size

<img width="32" src="../assets/icons/ProjectOpen.png">
In the original MD file image size is reduced as expected:

In the rendered webpage it's not:

ODE Solver properties: missing section caption

s. https://docs.open-systems-pharmacology.org/working-with-mobi-r/mobi-r-documentation/setting-up-simulation#output-intervals

In the old manual it looked like this:

Links are broken

Empty hint

Empty hint in https://docs.open-systems-pharmacology.org/working-with-mobi-r/mobi-r-documentation/setting-up-simulation#output-intervals

Describe portable versions

How to use portable versions of PK-Sim and MoBi (introduced in 7.2)

Update copyright pages with remarks from PR

see PR #7

Describe snapshots

Describe the snapshot-feature (introduced in 7.3)

Describe Draft watermark

Describe Draft watermark feature (introduced in 7.2)

Explain undefinedLiverEnzyme

Explain undefinedLiverEnzyme

(Better) description of path system in Mobi

(Better) description of path system in Mobi

Description of cumulated sensitivity is manual is wrong

The formula defined in the manual is not the one used in code!

whereas the code uses simple Sum of absolute values
https://github.com/Open-Systems-Pharmacology/OSPSuite.Core/blob/f75c2b2f6a639a8a8f27e4937358ad7819e87ba0/src/OSPSuite.Core/Domain/SensitivityAnalyses/SensitivityAnalysis.cs#L128

Describe "Identify individuals within a population analysis"

Describe "Identify individuals within a population analysis (e.g. individuals associated with the percentiles displayed)" feature (introduced in 7.2)

Add page explaining how to contribute to the documentation

Broken reference

S. last hint before Sum formulas

Screenshots made with german Windows

Some screenshots (e.g. in Section V.36 "Shared tools - Import and edit of Observed Data") are created with a Windows version set to german language.

Include pregnancy population

Include pregnancy population in the list of available populations (introduced in 7.2)

Broken reference

S. 3rd paragraph in Molecule parameters section:
If you enter a formula-defined or a state variable parameter, please refer to the general section defining how to use this functionality (???).

Describe BSA and dosage per BSA

Describe BSA and dosage per BSA (introduced in 7.2)

Check protein model description

Check if Protein model desciption is uptodate and adjust if required.
(check if model changes implemented in 7.1 are reflected)

Describe the option show/hide outliers in Box-Whisker plots

Describe the option show/hide outliers in Box-Whisker plots

Remove R from path so that the url do not look stupid

https://docs.open-systems-pharmacology.org/working-with-pk-sim-r/pk-sim-r-documentation/pk-sim-compounds-definition-and-work-flow#loading-existing-compounds-from-templates

because we are showing the registered symbol, the url are all messed up and it looks like we rae talking about a connection between PKSim and R

Suggestion would be to get rid of that

Describe Installation Validator Tool

Describe Installation Validator Tool (introduced in 7.1)

Describe "Intestinal solubility as table function of pH"

Describe "Intestinal solubility as table function of pH" (introduced in 7.3)

Integrate ontogeny documentation

Currently ontogeny documentation is standalone and not part of the manual.
It could be integrated as appendix.

Unnecessary hint

https://docs.open-systems-pharmacology.org/working-with-mobi-r/mobi-r-documentation/building-block-concepts#parameter-start-values

Update icons

Most icons are obsolete. THis should simply be updated in the image folder

https://github.com/Open-Systems-Pharmacology/docs/tree/master/assets/icons

And the name of the icon should be the name of the icon used in core!!!

Describe "Extract individuals from a population"

Describe "Extract individuals from a population" feature (introduced in 7.2)

• extract individuals from a Box-Whisker plot in a population simulation
• extract individuals from a population building block

Example is confusing

Setting up a Reaction Network example is pretty confusing.

After going through the whole exercise, you end up with a graph exactly like the final figure displayed.
Weirdly, the amount of product decreases over time and the amount of educt increases. This is confusing, since before it is explained in a note that the color blue means the substance is consumed, while molecules connected to the green dot are produced. So in the beginning we define the molecule "product" is produced (as we connect it to the green dot), and in the simulation we find its concentration decreases over time instead of increasing.

Some possibilities to "fix":

1. the initial value of the product can be set to 0
2. k2 can be chosen a lot smaller than k1
   In both cases, the second term in the formula k1*Drug/V*((Educt/V)/(Km+Educt/V)) - k2*Product/V then becomes small enough and we end up with a more comprehensive graph.

Explanation of negative values check

Add explanation and instructions for the user how to proceed.

Describe Command line interface (CLI)

Describe Command line interface (CLI) (introduced in 7.3)

Describe Import population from file

Also add hints for merging/adjusting existing population via Export/Import from CSV

Add explanation of "Use as suspension"

Add explanation of "Use as suspension" option in oral formulations

Add rabbit

Include rabbit into the list of available species (introduced in 7.1)

Describe "Add entry after each conversion of project and or building block in the history"

Describe "Add entry after each conversion of project and or building block in the history"

Improve description of active processes

E.g.

• explain in detail, how start amounts of proteins are calculated;
• explain the difference between relExp, relExpNorm and relExpOut and how they are calculated depending on Epithelial polarity, Localization in Tissue/Vascular Endothelium etc.

In general I think we would need new section in the manual, something like Model internals, explaining some tricky part of the model building.

Describe Adding transporter/enzyme activity in an already created population

In https://docs.open-systems-pharmacology.org/working-with-pk-sim-r/pk-sim-r-documentation/pk-sim-creating-populations

Sensitivity Analysis Description misleading

The sensitivity analysis in PK Sim allows a visualization for a summary of the relevant Parameters accounting for 90% of the cumulated sensitivity. The Manual describes the computation applying the sqrt to both, the cumulated sensitivities as well as to the total sensitivity in the denominator.
The plot actually visualizes parameters derived when neglecting the sqrt. Also, the formula in the manual is not considering absolute values

Describe "Value origin"

Describe "Value origin" (introduced in 7.3)