# README This manual describes the [Open Systems Pharmacology Suite](https://www.open-systems-pharmacology.org). 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. Documentation for the developers of the Open Systems Pharmacology Suite and more technical details are provided [here](https://dev.open-systems-pharmacology.org/). 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](/mechanistic-modeling-of-pharmacokinetics-and-dynamics/modeling-concepts/modeling-concepts-pbpk-modeling-systems-biology) ## 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](/open-systems-pharmacology-suite/modules-philsophy-building-blocks) ## 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-pk-sim/pk-sim-documentation/pk-sim-quick-guide) ## Working with MoBi® MoBi® focusing on modular model customization and extension as well as on pharmacodynamics in "Working with MoBi®". [Go to: Working with MoBi®](/working-with-mobi/mobi-documentation/first-steps) ## 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](/shared-tools-and-example-workflows/features-of-tables) ## Working with R The interfaces to the common computing environment R is described in "Working with R". [Go to: Working with R](/working-with-r/introduction-ospsuite-r) # Open Systems Pharmacology Suite Manual & Copyright Version 12 Update 1 Publication date September 2025 Copyright © 2025 [Open Systems Pharmacology Community](/references/references#115) The manual is provided “as is” without expressed or implied warranty. **Trademark information:** All trademarks within this manual belong to their legitimate owners. The Open Systems Pharmacology Suite uses the CVODES solver: Copyright (c) 2002-2021, Lawrence Livermore National Security. Produced at the Lawrence Livermore National Laboratory. Written by A.C. Hindmarsh, D.R. Reynolds, R. Serban, C.S. Woodward, D. J. Gardner, S.D. Cohen, A.G. Taylor, S. Peles, L.E. Banks, and D. Shumaker. UCRL-CODE-155950 (CVODES) All rights reserved. Please, refer to the LLNL website for detailed information on licensing: * * Internet: * Support: * # How to Contribute Welcome to the [docs.open-systems-pharmacology.org](http://docs.open-systems-pharmacology.org) Contributor guide! The documentation for the Open Systems Pharmacology Suite is open source and hosted on GitHub. Despite all the efforts to maintain and update the documentation, there will always be small grammar and spelling errors sliding through the cracks as well as sections of the documentation that are not clear enough, missing or outdated. While you can create issues in the [docs repository](https://github.com/Open-Systems-Pharmacology/docs/issues) to report those errors or omissions, it will often be faster and easier to submit your edits directly to be reviewed by the documentation core team. This guide aims at describing the workflow to contribute to the documentation. ## Requirements The only requirement to contribute to the documentation is to have a GitHub account. If you do not have an account, you can [create one](https://github.com/join) for free in a few seconds. ## Edit of existing documents Each page available on the docs website corresponds to a file hosted on GitHub that can be edited. Clicking on the `Edit on GitHub` button will take you to the source file on GitHub.![Edit on GitHub](/files/-LOR2W3F7eaPpux7Fhei) Next, click the pencil icon, as shown in the following figure to edit the article.![Edit](/files/-LOR2W3IVhetUCEzEE8I) {% hint style="info" %} If the pencil icon is grayed out, you need to login to your GitHub account. {% endhint %} {% hint style="info" %} Make your changes in the web editor. Formatting of the documentation is based on the so called **Markdown** syntax. The description of this lightweight and easy-to-use syntax can be found [here](https://guides.github.com/features/mastering-markdown/). You can click the Preview changes tab to check formatting of your change. {% endhint %} Once you are done with your changes, scroll to the bottom of the page. Enter a title and description for your edits and click `Propose file change` as shown in the following figure: ![Propose file change](/files/-LOR2W3VMmAvQRwvHlsx) Now that you have proposed your changes, you need to ask the documentation core team to incorporate them into the documentation. This is done using something called a **pull request**. When you clicked on `Propose file change` in the figure above (and on `Create pull request` after that), you should have been taken to a new page that looks like the following figure: ![Open pull request](/files/-LOR2W3Z3QY9eoeEmGe2) Review the title and the description for the pull request, and then click `Create pull request`. That's it! The documentation core team will be notified and review your changes. You may get some feedback requesting changes if you made larger changes. ## Adding new content The process is slightly more complicated as you need to create a new content file and incorporate it into the existing documentation. We would be happy to help you do that if you need some support. Simply open an issue in the docs repo describing what you want to add and where and we'll get in touch with you. ## Rich content ### Note, hints and callout Provides a great way to bring the reader's attention to specific elements. By surrounding your text with `{ % hint style="xxx" %}` and `{ % endhint %}`, a visual clue will be created for your content, making it pop out For example: using the style `note`, we can create the following visual element {% hint style="info" %} This is a note {% endhint %} Available styles are: * tip * note * warning * info # Best Practices # Introduction The versatile nature of physiologically based pharmacokinetic (PBPK) modeling facilitates many opportunities of application but at the same time also for different approaches in terms of execution. This inevitably introduces the questions on way of working and best practices. How should model development, including challenges addressed and assumptions made, be conducted and reported? How should analyses be performed at different stages in drug development to ensure robust results with confidence, reproducibility and traceability? To guide the users of the OSP-Suite we here present our view on best practices for PBPK modeling. The material is categorized under the sections Development, Evaluation, Application\&Simulation and Documentation including a repository of relevant literature to facilitate further reading on the topic. ![Guide to PBPK model development, evalution, simulations and documentation](/files/G2qO28IO45QHLl0zQzGS) To note, there are a number of existing review, overview, tutorial, and guidances available to the PBPK Community. This site is not intended to rewrite those materials but instead to serve as a landing page for individuals seeking to learn or to branch further into PBPK modeling. A sampling of existing learning content is listed below: \[[123](/references/references#123)] - \[[130](/references/references#130)] # Model Development Prior to starting on model development, a requirements analysis should be conducted to assess and outline a model development strategy: * the model purpose, i.e. its context of use which should include * Organism / population characteristics (biometrics, genotype, disease state, …) and the * Experimental design * the observed data (e.g., QSA/PR, in-vitro, or in-vivo) available for model development * Non-clinical & clinical data considerations, e.g., would it help the model development of a human PBPK model to develop an animal PBPK model (e.g. for FIM or if no IV data was collected in humans but in animals)? * Individuals data vs population mean data: how will this impact model evaluation and qualification (variability and uncertainty assessments (Considered in Sections “3. Model Evaluation” and “4. Model Applications”))) * and the model evaluation & qualification strategy (Section “Model Evaluation”) This requirements analysis should then be condensed into specifications (i.e., a strategy) for model development & qualification and documented within an analysis plan (see Figure1). ![Model development](/files/wRpeefAhIJHW4psoskLD) Figure 1: Predict, Learn, and Confirm cycle in IVIVE-PBPK model development (adopted from \[[168](/references/references#168)]). Availability and quality of data for model development is the key element and has to be judged in the context of use (see “Useful Literature” below). **As an example:** data quality, e.g. input parameters for compound PK properties such as fraction unbound in plasma (fup) may have been precisely measured or only predicted with some uncertainty through QSPR models. The latter might contain too much uncertainty and not be appropriate in the context of precision dosing estimates for a clinical trial, but might well be suitable for risk assessment in environmental toxicology. Thus, the key is to make yourself aware of the limitations of the available data considering: * accuracy and suitability of data for PBPK model development. * in which systems the data have been collected * fu or lipophilicity measures (partitioning media used, neutral or acid/base compound) * solubility (measured in water or biorelevant media) * dissolution profiles (what apparatus was used and at which pH values). What should not be neglected in the requirements analysis, is the evaluation of the information, data and structure which the PBPK framework and associated databases or “add-on modules” contain. Compound properties and context of use will require decisions and sound qualification on what to select from available options, e.g.: * which partitioning calculation method to choose based on compound properties * how to extend the model (with e.g. “add-on modules” found in modeling literature) if required to fulfill its purpose (i.e., customizing default model equations and structure to account for e.g. specific mechanisms of distribution or new organ compartments not covered by the default PBPK model structure). ## Useful Literature * IVIVE / ADME \[[159](/references/references#159)] * This best practice provides an overview of strategies for first in human prediction based on preclinical modelling. A Review of relevant scientific publications and case examples are provided as well. * Absorption \[[160](/references/references#160)] * This review provides an overview of the determinants of intestinal absorption and first-pass elimination of drugs and focuses on the principles and applications of conventional in vitro–in vivo extrapolation (IVIVE) methods to predict Fabs, FG, and FH in humans. * Distribution \[[161](/references/references#161)], \[[162](/references/references#162)], \[[163](/references/references#163)], \[[164](/references/references#164)] * These papers provide the state of art of mechanistic calculation of steady state tissue:plasma partition coefficients (Kt:p) of organic chemicals in mammalian species was developed. * Metabolism \[[165](/references/references#165)] * Benet and Sodhi proposed future pathways that should be investigated in terms of the relationship to experimentally measured clearance values, rather than model-dependent intrinsic clearance * Transporters & Excretion \[[166](/references/references#166)], \[[167](/references/references#167)] * These data demonstrate the promise of using IVIVE of transporter-mediated drug clearance and highlight the importance of quantifying plasma membrane expression of transporters and utilizing cells that mimic the in vivo mechanism(s) of transport of drugs. ## Further Reading * Data-driven model refinement and qualification (e.g. \[[168](/references/references#168)], \[[124](/references/references#124)] ) * The papers describe a definition of, “qualification”, a how-to work flow, regulatory perspective, and an case example for model refinement * Expansion to a PBPK-QSP Model (Platform) (e.g. \[[171](/references/references#171)], \[[172](/references/references#172)]) * These papers highlight complex integrations of PBPK and PD/QSP for building disease platform level PBPK-QSP models, which include often efficacy-relevant target/receptor kinetics and occupancy, and deposition. # Model Evaluation 1. Get in the “Model Evaluation Mindset”: 1. In your modeling analysis plan, define what questions you are planning to address with the model, i.e. - the “context of use (COU)”. 2. Consider the risk that exists if the model you choose leads to a biased or imprecise result. 3. Define performance requirements that the model will need to achieve for it to be a successful tool for addressing those questions (aka “model credibility”). Gear your model evaluation standards to enable you to determine whether or not your model has achieved the necessary performance requirements. 4. Assess your model credibility as part of the model development. If a candidate model fails to meet requirements, continue to refine. 5. Document evidence of credibility 2. Development of a **Credibility Assessment Framework** \[[151](/references/references#151)] can assist you in defining, conducting, and evaluating the model performance requirements. 1. The Kuemmel et al 2020 paper provides rubrics, e.g., for establishing an assessment of model risk 2. Consider, too, establishing more quantitative criteria for your model, as well. What level of error (MAE, RMSE, MRD, GMFE, ..., sensitivity to uncertainty in parameter values, etc) will be acceptable on which metrics (AUC, Cmax, and/or other). In some cases, for example, you may be able to tolerate a much larger-fold error (if it’s a rough projection of first-in-human dosing) compared with a case where a trial waiver is being considered, e.g., using a PBPK-based DDI projection. These goal posts will likely adjust in a manner consistent with the risk score. ![Model evalution](/files/bOJqvVsqM2nMtSJlJDPf) [**Overview of the ASME V\&V 40 risk‐informed credibility assessment framework**](https://www.ncbi.nlm.nih.gov/pmc/articles/PMC6966181/)**; COU, context of use; V\&V, verification and validation.** 3. Goodness-of-fit diagnostics to consider during model development and for the final model evaluations include the following: 1. Quantitative metrics of predictive performance for exposure endpoints of interest, * e.g., half-life, Cmax and AUC * Precision and bias calculations: RMSE, mean absolute error (MAE), mean relative deviation (MRD) of the predicted plasma concentrations for all observed and the corresponding predicted plasma concentrations as well as geometric mean fold errors (GMFEs) 2. Graphics 1. Overlay of observed and predicted concentration-time profiles. Depending on your focus (include plots on linear scale (e.g. focus on absorption and Cmax) and / or logarithmic scale (e.g. focus on Distribution and elimination)!). \[[152](/references/references#152)], \[[153](/references/references#153)] 2. Observed vs predicted of derived metrics, e.g., Cmax and AUC \[[152](/references/references#152)] 3. Precision and bias metrics (e.g., MAE, RMSE) to compare across models or other methodological approaches \[[153](/references/references#153)] 3. Standards for Model Evaluation Metrics \[[139](/references/references#139)],\[[143](/references/references#143)] 4. Strategies for model development and evaluation 1. Case-based strategies for different application scenarios \[[154](/references/references#154)] 4. Acknowledge parameter value sources and expectations of reliability. Use sensitivity analyses to evaluate the impact that variability or uncertainty in those values might have on model performance: 1. For evaluating, acknowledging, and identifying sources for parameter values, additional considerations include pedigree tables (), and similar approaches, e.g., 1. Braakman S, Paxson R, Tannenbaum S, Gulati A. Visualizing Parameter Source Reliability and Sensitivity for QSP Models. ACoP10 Oct 2019 2. Gulati A, Tannenbaum S. Using visualization to address the reliability of sources of initial parameter values in a Quantitative Systems Pharmacology (QSP) model. ACoP9 October 2018 2. PBPK and QSP modeling requires an understanding and acknowledgement of a priori (structural) and a posteriori (practical) identifiability, as well as characterization of uncertainty in the model parameters. Local and global sensitivity analyses can be used to quantify the influence of parameter variation on predictive performance. 1. A sampling of reviews that provide an overview of these techniques includes: \[[155](/references/references#155)], \[[156](/references/references#156)], \[[157](/references/references#157)], \[[158](/references/references#158)] 2. An open-source example of global sensitivity (Sobol) analysis is available here: 5. Documentation of the model development and evaluations should include evidence from the model credibility assessment. This also should include documentation of the planned and execution verification and validation, e.g., to cover these areas of the PBPK model development and evaluation: 1. Verification activities will ensure the correctness of implementation of model code and the accuracy of the underlying software and algorithms. Verification will be accomplished via test scripts, peer code reviews, built-in model sanity checks (e.g., PBPK mass-balance checks), etc. 2. Validation activities will ensure the accuracy of the overall model, the validity of model assumptions, and ability of the model to answer the specific questions of interest. Validation will be accomplished by comparison of model predictions with clinical data or other comparators. # Application Simulation ## Intended-use scenario-based applications: * DDI * Application Case Examples * Case-scenario of an industry-application PBPK bottom-up modeling approach used to evaluate the DDI potential of acalabrutinib and its active metabolite, with CYP3A inhibitors and inducers \[[149](/references/references#149)]. * Model Template Development * Türk’s paper describes a comprehensive workflow of DDI module in PK-Sim and the Supplementary Materials to this manuscript were compiled as one comprehensive reference manual with transparent documentation of the model performance to support DDI investigations during drug development, labeling, and submission for regulatory approval of new drugs \[[145](/references/references#145)]. * Special Populations / Organ Impairment * Pediatrics * Yun’s paper determined the appropriateness of the virtual individual creating algorithm in PK-Sim® in predicting PK parameters and their variability in children by comparing a model output, clearance, to observed data. Identified the critical system specific input parameters within a pediatric PBPK model structure for estimating exposure in children via a sensitivity analysis \[[147](/references/references#147)]. * A brief overview of the development of pediatric physiologically based pharmacokinetic (PPBPK) models, the challenges of uncertain systems information, and finally performance verification considering recent regulatory guidance \[[138](/references/references#138)]. * Pregnancy * These manuscripts provide overview of pregnancy model in PK-Sim and its major aspect of the model and physiology changes \[[132](/references/references#132)] * Organ Impairment * Reviews * PBPK predictions can help determine the need and timing of organ impairment study. It may be suitable for predicting the impact of RI on PK of drugs predominantly cleared by metabolism with varying contribution of renal clearance \[[136](/references/references#136)]. * CKD * The renal diseases also affect drug metabolization by the liver. Tan et al. provides a comprehensive workflow used for investigation of pharmacokinetics on patients with CKD \[[144](/references/references#144)]. * Liver * PBPK Modeling for prospective dose recommendations and efficacy/safety assessment in special populations (when consistent clinical data are lacking). Example for a PBPK model to predict the effect of moderate and severe hepatic impairment on the PK of alectinib to best inform clinical study design \[[141](/references/references#141)]. * Virtual Bioequivalence (VBE) * Average bioequivalence studies have been required by the FDA and the EMA. These publications explore a workflow and discuss data requirements to run Virtual BE using PBPK \[[139](/references/references#139)], \[[140](/references/references#140)]. * Regulatory Review * This report reviews the use of PBPK in decision-making during regulatory review. The report also discusses the challenges encountered when PBPK modeling and simulation were used in these cases and recommends approaches to facilitating full utilization of this tool.It also summarize general schemes of PBPK simulation and propose procedures to obtain necessary data to construct PBPK models. In order to fully utilize PBPK in drug development and regulatory review, it is critical to adequately define mechanisms of drug disposition and understand general physiological perturbations related to diseases,age, and organ dysfunction \[[148](/references/references#148)]. * This white Paper summarises the FDA's view how a framework for evidential criteria for PBPK models can be established. With that the FDA reached out to the scientific community to stimulate a discussion about this topic \[[137](/references/references#137)]. * Overview on use of PBPK for submissions to the FDA. Discusses limitations and knowledge gaps in integration of PBPK to inform regulatory decision making, as well as the importance of scientific engagement with drug developers who intend to use this approach \[[135](/references/references#135)]. ## Simulation (i.e. application) design / strategy considerations: * Population-level vs mean * This case study for Caffeine shows that individual pharmacokinetic profiles can be predicted more accurately by considering individual attributes and that personalized PBPK models could be a valuable tool for model informed precision dosing approaches in the future \[[134](/references/references#134)]. * Workflow Review * This review of several case studies provides is for a better understanding of the absorption, distribution, metabolism and excretion (ADME) workflow of a drug candidate, and the applications to increase efficiency, reduce the need for animal studies, and perhaps to replace clinical trials. The regulatory acceptance and industrial practices around PBPK modeling and simulation is also discussed \[[150](/references/references#150)]. * Hypothesis generation * The aim of this paper was to develop an analysis framework to investigate whether population modelling approach can be used to estimate PBPK model parameters from clinical PK data and establish the required criteria for such estimations \[[131](/references/references#131)]. * Regulatory Confidence * It is a perspective case of workshop entitled “Application of Physiologically-based Pharmacokinetic (PBPK) Modeling to Support Dose Selection” was hosted on March 10, 2014 by the US Food and Drug Administration (FDA) at its White Oak Campus in Silver Spring, MD. The workshop endeavored to (i) assess the current state of knowledge in the application of PBPK in regulatory decision-making, and (ii) share and discuss best practices in the use of PBPK modeling to inform dose selection in specific patient populations \[[146](/references/references#146)] * This white Paper summarises the FDA's view how a framework for evidential criteria for PBPK models can be established. With that the FDA reached out to the scientific community to stimulate a discussion about this topic \[[137](/references/references#137)]. * Case-based strategies for different application scenarios * This work presents a systematic assessment of the current challenges to establishing confidence in PBPK models with respect to parameter estimation and model verification in each of the three major areas of PBPK application absorption prediction, exposure prediction in a target population, and DDI risk assessment during drug development \[[142](/references/references#142)]. # Documentation While PBPK modelling is applied to inform decision making in the pharmaceutical industry to e.g. inform go/no-go decisions, formulation development, a dosing strategy in pediatrics or a DDI strategy one should keep in mind that PBPK modelling is a robust tool to support drug/chemical safety or toxicity risk assessment in general. Independent of whether PBPK modelling is used for internal decision making or for decisions by regulators, a minimum level of documentation is recommended to facilitate traceability and, later on, review by regulators. This minimum level of documentation should allow for establishing the link between data, data transformations and manipulation, final model/simulation code, and conclusions in order to facilitate traceability. The manuscript “Good practices in model-informed drug discovery and Development (MID3): Practice, Application and Documentation” \[[169](/references/references#169)] provides an overview on different levels of documentation (memo, report), a suggestion for documentation of analysis plans and reports including high-level guidance for authors with respect to content and audience. Guidance on documentation of assumptions and assessment of assumptions during model development is also provided . A recent publication by Tan et al. focuses on PBPK model reporting for chemical risk assessment, expanding the already existing guidances for pharmaceutical applications by recommending additional elements that are relevant to environmental chemicals, providing a more general and harmonized framework for reporting of PBPK models \[[170](/references/references#170)]. ## Documentation during the conduct of an analysis It is recommended to create a summary of the parameter identification steps describing all relevant steps and tested models leading to the current best model. It is recommended to capture the following information: * Analysis dataset used for parameter identification * Simulations included * Rationale for the model / hypothesis tested * Outcome/evaluation of the parameter identification step * Parameters used in final model Most of the commercial PBPK software offer a built-in tracking of parameter identification steps such as e.g. the journal function in OSP. ## Reporting (including analysis plans) of PBPK analysis FDA and EMA have both issued guidance documents for the industry on reporting of PBPK analysis outlining the recommended format and content of a report for regulatory submissions \[[125](/references/references#125)], \[[126](/references/references#126)]. The EMA guidance clarifies their expectation on qualifying a PBPK platform for the intended use. A more detailed overview on sections to be included in such a report and guidance on expected content in each section is provided in Table 4 of a review on “Physiologically Based Pharmacokinetic Model Qualification and Reporting Procedures for Regulatory Submissions: A Consortium Perspective” by \[[128](/references/references#128)]. The outlined sections are in line with the MID3 recommendations and the FDA guideline. Supplements to this publication include a template for analysis plans and reports. A more recent publication \[[170](/references/references#170)] focuses on PBPK model reporting for chemical risk assessment applications. It expands the existing guidances \[[125](/references/references#125)], \[[126](/references/references#126)], \[[128](/references/references#128)] for pharmaceutical applications to support the assessment of the safety of environmental chemicals. The publication provides very detailed expectations towards the content of each section which go beyond the level of detail as provided by the existing guidelines. While Tan et al. address underlying modelling assumptions as part of the method section, Marshall et al. and Shebley et al. suggest a stand-alone section including documentation of assessing the impact of uncertainties in the assumptions taken. # Modeling Concepts # PBPK Modeling - Systems Biology Systems biology is a multidisciplinary field of research. It is about understanding and investigating biology from a systems perspective. That is to say, the focus is not on isolated parts or processes, but on their interaction by which a certain behavior is generated or a certain task is fulfilled. In modern science and engineering, systems are often studied using mathematical models. Mathematical models can be used to aggregate and integrate existing knowledge with the aim of systematically analysing system behaviour, testing and generating hypotheses, and planning the next experimental steps. The idea of using mathematical models to investigate biology is not new. What is relatively new is the increasing recognition and appreciation that mathematical models can be an efficient way of learning and can form the basis for decision-making. Molecular complexity forms the basis of life, and it is clear that system boundaries and certain levels of detail within a model may be limited. While experiments are and will remain an essential part of biological (and systems biological) research, in line with many "systems biologists", we consider mathematical models as the core discipline of systems biology. Consequently, in this manual, if we speak simply of models we mean mathematical models and we will indicate if another form of model is used. The content of this manual is naturally selected and biased. Systems biology includes many levels of biological diversity, but we will focus on organisms and topics of broader relevance in pharmaceutical research and development, i.e., systems pharmacology. However, many facets of the software can be used beyond systems pharmacology. While the very early phases of drug development do generally not involve work on whole organisms (animals or humans), the late preclinical phase includes animal experimentation mainly in mammals such as mice, rats, dogs, or monkeys before entering the clinical phase, where the focus is on human participant research as outlined below. Various modeling approaches have been developed to support investigations on different scales [39](/references/references#39). As outlined above, we will focus on systems pharmacology, which can be viewed as a mechanistic approach to the study of pharmacodynamics and pharmacokinetics. ![Phases, costs, and biological systems used in drug development](/files/-LOWPzSRwCEvHqB6aELr) # PK and PD Modeling Pharmacokinetics (PK) may be defined as what the body does to the drug, as opposed to pharmacodynamics (PD), which may be defined as what the drug does to the body \[[4](/references/references#4)]. The site of action of a pharmacological substance might be restricted to specific tissues or cells, which is why a quantitative estimate of the amount of administered substance that is available at the site of action is required. This question is the subject of pharmacokinetics, and different modeling techniques are well-established in pharmaceutical research to support its investigation. So far, the most widely used approach is to establish descriptive and comparatively simple compartmental PK models that can be well identified based on available data. Often these models are applied to population PK data using nonlinear mixed-effect techniques (NLME), e.g., to quantify sources of population variability or covariate effects. Besides PK, such models may also include a description of a compound's effects (PD), for example, in the form of a simple hyperbolic or sigmoid concentration-effect relation (Michaelis-Menten, Hill, or Emax type). In classical pharmacokinetic modeling, the aim is to fit a comparatively simple model to experimental data in order to determine pharmacokinetic parameters from the fitted concentration-time course. These parameters are used to characterize and quantify the behavior of the investigated substance in general or in a certain clinical trial and, potentially, to extrapolate to situations that have not already been investigated. In contrast to the rather phenomenological consideration of drug PK in compartmental models, physiologically–based pharmacokinetic (PBPK) models aim for a detailed representation of physiological processes, as will be summarized in the following. Consequently, PBPK modeling is based on the mathematical description of physical and physiological processes, and in the framework of PBPK modeling, a genuine simulation of the pharmacokinetic behavior using this description is performed. Also, the PD can be represented mechanically, as discussed in [Modeling Concepts - PD and Reaction Network Modeling](/mechanistic-modeling-of-pharmacokinetics-and-dynamics/modeling-concepts/modeling-concepts-pd-and-reaction-network-modeling). A good starting point for further reading can be found in \[[65](/references/references#65)]. ![Structure of compartmental PK model (A) and PBPK model (B)](/files/-LOWQ1x82IwLqAhUXQsr) # Principles of PBPK Modeling ## Introduction to PBPK Modeling Physiologically-based pharmacokinetic (PBPK) modeling is a mechanistic approach to describe the pharmacokinetics of a substance based on substance-specific properties and mammalian physiology, for which a substantial amount of prior biological information is used for model building, \[[92](/references/references#92)], \[[93](/references/references#93)], \[[95](/references/references#95)], \[[96](/references/references#96)], \[[97](/references/references#97)], \[[14](/references/references#14)], \[[22](/references/references#22)], \[[69](/references/references#69)], [\[116\]](/references/references#116) - \[[120\]](/references/references#120). The general idea, introduced as early as 1924 \[[31](/references/references#31)], is to divide the body into physiologically relevant compartments, mainly the relevant organs, and to set up a mass balance equation for each compartment describing the fate of the substance within that compartment \[[76](/references/references#76)]. In PK-Sim®, a physiological framework model is provided where the mammalian body is divided into containers representing relevant organs or tissues and arterial and venous blood pools connecting the different organs through the blood flow. Organs are further subdivided into several subcompartments that describe essentially the vascular space, divided into plasma and (red) blood cells and the avascular space, divided into interstitial and cellular space. Such a model framework corresponds to a detailed compartmental model and provides the structural basis to describe the behavior of a substance. For the simulation of the whole body, all mass balance equations are combined in a system of interdependent differential equations. In the simplest version of this system, all organs are connected in parallel between the arterial and venous blood pools, such that the blood flows from arteries to veins, except in the lung, where the circulation is closed by a blood flow in the opposite direction. When carrying out a simulation, this system of time-dependent differential equations is solved numerically. The primary results of such PBPK simulations are concentration-time courses of the compound in the various compartments explicitly described in the equations. This means that besides the plasma concentration, at least one concentration curve for each organ is included in the output. Of course, derived PK parameters such as the area under the curve (AUC) or the maximum concentration (Cmax) can be calculated based on the primary output. PBPK can also be well understood within ADME logic, which is further detailed below. ## (L)ADME logic and routes of administration The pharmacokinetics of a substance can be understood by considering its (liberation), absorption, distribution, metabolism, and excretion (ADME). While intravenously administered substances are directly available in the systemic circulation for distribution, substances administered, e.g., orally, subcutaneously, or via inhalation, must be absorbed first. Also, in some cases, the substance might not be directly available for absorption, but needs to be liberated first, in case an extended LADME scheme is relevant. ### Liberation Depending on the formulation of a substance, it might not be directly available for absorption processes. Certain formulations liberate the substance in a more or less controlled fashion, and these processes can be included in PBPK models. Further details on modeling liberation in PK-Sim® are described in [PK-Sim® - Formulations](/working-with-pk-sim/pk-sim-documentation/pk-sim-formulations). ### Absorption Substances not administered intravenously generally must be absorbed before being available in the systemic circulation. The most common route of administration for which absorption is a critical issue is oral (per os, PO) administration. Factors such as gastric emptying and intestinal transit time, stability and solubility of a substance or formulation, as well as the permeability across the intestinal wall based on passive and active transport processes, are essential for the fraction of a substance absorbed into the systemic circulation. Bioavailability is further determined by potential first-pass metabolism as described below. Historically, a plug-flow-with-dispersion model was used in PK-Sim® \[[93](/references/references#93)]. From version 5.0 on, a compartmental gastrointestinal model is used, which is further detailed and discussed in \[[79](/references/references#79)] and \[[80](/references/references#80)]. ### Distribution After reaching systemic circulation, the compound may distribute into tissues and organs, decreasing the plasma concentration. The (apparent) volume of distribution is an important PK descriptor, theoretically defined as the volume in which the total amount of drug would need to be uniformly distributed to produce the given plasma concentration of a compound. However, the physiological processes that determine this volume may be complex. The basic passive processes, which determine the behavior of a substance in an organ, are mass transport via the blood flow, permeation from vascular space into organ tissue, and partitioning between blood plasma and organ tissue. The level of detail used for the description of these processes in a PBPK model can vary significantly. For the description of the passive physical processes involved in partitioning into the organs, usually two concepts are distinguished: blood flow-limited and permeation-limited partitioning. In the first case, all organs are assumed to be well-stirred compartments that equilibrate instantaneously with the plasma, and the time constant for the distribution of a substance into the peripheral organ is determined only by the blood flow rates. Alternatively, in models with permeation limitation, a permeation barrier is assumed between blood and organ tissue, resulting in a permeability dependence of the distribution and the corresponding time constants. Other important parameters determining the distribution behavior are the partition coefficients between the organ tissues and the blood plasma. These partition coefficients are given by the tissue to plasma concentration ratio under steady state conditions. Besides the passive processes described above, active transport processes or binding to proteins, including the target, can strongly influence the distribution behavior. The relative contribution of different processes to distribution also depends on the type of the molecule. The blood endothelium in the different organs often does not constitute a major distribution hurdle for small molecules. An exception is the significant blood-brain barrier. For larger molecules such as biologics, endothelial permeation can significantly impact the PK, and additional processes, such as lymph flow, are important for recirculation. Further details and options for modeling distribution in PK-Sim® are described in ["Partition coefficient calculation methods”](/working-with-pk-sim/pk-sim-documentation/pk-sim-compounds-definition-and-work-flow#definition-of-new-compounds-in-pk--sim). ### Metabolism Most substances are metabolized by enzymes in the organism. Often, two distinct phases are distinguished: Phase I enzymes catalyze modifications that generally add functional groups to non-polar molecules; Phase II enzymes can then conjugate soluble molecules to these groups to allow better elimination via the kidney or the gall bladder. The products of such biotransformation steps are referred to as metabolites. If they are not active, they are often not further considered. However, metabolites can also constitute the pharmacologically active form of the substance or be responsible for side effects. Generally, the liver is considered the most relevant organ for biotransformation. However, most metabolizing enzymes are also expressed in various other organs, even though often to a lower extent. Nevertheless, extrahepatic metabolism can be very important. Mucosal clearance in the intestinal wall is just one prominent example. Together with first-pass clearance in the liver, this process also influences the bioavailability of a substance \[[77](/references/references#77)]. Metabolism is generally an active and substance-specific process. While the enzyme equipment is a property of the organism, it has to be considered for each substance for which enzymes are relevant. Further details on modeling metabolism in PK-Sim® are described in the section [ADME Properties](/working-with-pk-sim/pk-sim-documentation/pk-sim-compounds-definition-and-work-flow#adme-properties-tab). ### Excretion/Elimination Compounds and their metabolites are generally removed from the body via excretion or elimination processes. The two most prominent routes of excretion are via the kidney into urine and via biliary excretion into the intestine and further into the feces. During the latter process, reabsorption can lead to entero-hepatic circulation of a substance. While biliary secretion is generally mediated via active transport, urinary secretion can be passive (glomerular filtration) or also due to active transport (tubular secretion). Other special routes of elimination can include exhalation via the lungs. Just like the metabolization processes, the transporter "equipment" is a property of each individual organism. For each substance, it has to be considered which transporters are relevant and whether or not the substance is subject to glomerular filtration. Further details on modeling excretion and elimination in PK-Sim® are described in [ADME Properties](/working-with-pk-sim/pk-sim-documentation/pk-sim-compounds-definition-and-work-flow#adme-properties-tab). ## PBPK model parameterization Due to its physiological basis, most parameters in a PBPK model are independent of substance knowledge or PK measurements. For example, information on blood flow rates, compartment volumes, or composition, e.g., in terms of volume fractions of water, proteins, and lipids, can be implemented independently of the substance. For establishing PBPK models to describe virtual humans, the physiological knowledge is not restricted to average individuals. For many parameters, their distribution within different populations is known in an age-dependent or subject-specific manner, allowing population PK predictions or extrapolations rather than fitting to data for interpolation. PBPK models can also be established for different animal species. With an established animal PBPK model at hand, for example, the physiological parameters can be substituted to make a first prediction for humans. The physiological correspondence of parameters enables both a good interpretation of results as well as a translation to new scenarios of application. Consequently, PBPK models are well-established in environmental toxicology and risk assessment fields and are becoming increasingly popular in pharmaceutical research. In addition, PBPK models automatically provide exposure estimates at the site of action and, therefore, provide a natural basis to build multiscale PK/PD models and thereby provide a good platform for knowledge integration along the pharmaceutical research and development process \[[85](/references/references#85)]. Besides this general information on mammalian physiology, PBPK models use generic distribution models. Using these models, only a few basic physicochemical parameters of the substance, such as molecular weight, lipophilicity, and protein binding, can be used to determine relevant passive processes, such as permeabilities across membranes and partition coefficients between compartments, to describe the PK behavior. Additional parameters are required for the representation of active processes, such as transport or enzyme-catalyzed metabolization. # Expression Data for PBPK Modeling The most prominent examples of proteins that affect PK are enzymes that catalyze the metabolism of drugs or transporters that can heavily influence drug absorption or distribution. Proteins can also include those which a drug binds to, either by design (drug-target interaction) or as an off-target interaction or side-effect. Such binding can also influence the distribution, as well as the metabolism and excretion of the drug. In physiologically-based PK modeling approaches, it is desirable to mechanistically reflect such relevant drug-protein interactions. In some cases, the addition of one specific protein into the most relevant organ is sufficient to describe a process, e.g., cytochrome P450 3A4-mediated metabolization in the liver. In other cases, it may be necessary to consider protein levels in more than one organ. The integration of a protein expression database with PK-Sim makes it easy to assign parameter values for the involved proteins to account for differential protein expression in various organs and assign them to virtual individuals. As such, the user describes the absolute amount of protein in one reference organ, and through the use of relative expressions as generated with the protein database, the protein concentrations are fixed for all organs where the protein is present. Details on how to use the protein expression database are described in [PK-Sim® - Expression Data](/working-with-pk-sim/pk-sim-documentation/pk-sim-expression-profile). See \[[46](/references/references#46)] for an example that demonstrates how taking into account protein expression leads to an increase in PBPK model quality. Alternatively, the user can assign one set of kinetic parameters characterizing the drug-protein interaction (e.g., kcat and Km, or kon and koff) and use this in all organs. # Modeling of Proteins Therapeutic proteins are an increasingly important class of drugs. Particularly, monoclonal antibodies are used for different indications including cancer, inflammatory and autoimmune diseases \[[88](/references/references#88)]. These engineered antibody fragments with tailored pharmacokinetic properties have the potential to be used as diagnostic and therapeutic agents \[[34](/references/references#34)]. PK-Sim® offers a model specifically designed to describe the pharmacokinetics of proteins and other macromolecules [\[114\]](/references/references#114). The pharmacokinetics of protein therapeutics are governed by a number of unspecific and specific processes, which have to be incorporated to describe the pharmacokinetics of protein therapeutics. This includes \[[42](/references/references#42)]: * Exchange across the vascular endothelium between plasma and the interstitial space by convection and diffusion. * Return of the drug from the interstitial space of the organs to the circulation by lymph flow. * Degradation and protection from degradation by neonatal Fc receptor (FcRn) in cellular endosomes. * Target-mediated disposition and clearance. This model was developed by extending the standard model for small molecules by a description of the transcapillary drug exchange, lymph flows and endosomal space including drug degradation and protection from degradation by the FcRn receptor. Within this model, the transcapillary exchange of the drug is described by the two-pore formalism \[[58](/references/references#58)], \[[57](/references/references#57)], \[[3](/references/references#3)]. According to this theory, the barrier between plasma and interstitial space is described as a membrane consisting of two types of pores: a few large and many small ones. Macromolecules can pass through these pores by convection as well as diffusion. To describe these processes, the endothelial permeabilities and osmotic reflection coefficients of the drug for the different organs are calculated within PK-Sim® from the Stokes radius of the drug and endothelial properties like pore radii and hydraulic conductivity \[[58](/references/references#58)]. The FcRn sub-model is based on the model published by Garg and Balthasar \[[26](/references/references#26)]. The fraction of the drug that is bound to FcRn within the endosomal space is recycled to the plasma and the interstitial space, whereas the fraction not bound to FcRn is cleared from the endosomal space. In PK-Sim®, endosomes represent the endosome in the vascular endothelium only and serve as a compartment for the protein. Endogenous IgG is also represented, which competes with the drug for the FcRn receptor. The clearance of the drug thus depends on its affinity to the FcRn receptor, the endosomal concentration of endogenous IgG, and the endosomal concentration of the FcRn receptor. The main difference to the model published by Garg and Balthasar \[[26](/references/references#26)] is that in the PK-Sim® model, there is binding to the FcRn receptor, which is explicitly represented, and, thus, different affinities to the FcRn receptor can be specified for the drug and the endogenous IgG. Nonspecific binding or specific binding of the therapeutic protein to its target can be added within PK-Sim®. Specific binding within a tumor or a detailed description of target-mediated clearance by receptor internalization can be added within MoBi® based on a PK-Sim® protein. # PD and Reaction Network Modeling Pharmacodynamics (PD) describes the interactions of drugs with the organisms. This includes binding of drugs to their targets (which may also be relevant for understanding the PK) and resulting direct or indirect effects. Pharmacodynamics can also relate drug concentration profiles (PK) to clinical endpoints, which usually requires consideration of disease progression. Various modeling approaches are used to analyze PD or disease progression, either alone or in combination with PK. Simple models use a sigmoidal function to relate a concentration to its effects (e.g., Hill, IC50, Emax-shape). Here, the maximum effect and the concentration that corresponds to half the maximum effect are typical curve characteristics. Such approaches can be combined with advanced statistical methods, as the effect of a drug is rarely fully deterministic. Inter-individual or inter-occasion differences can be investigated and quantified in such a way, see [Modeling Concepts - PK and PD Modeling](/mechanistic-modeling-of-pharmacokinetics-and-dynamics/modeling-concepts/modeling-concepts-pk-and-pd-modeling). Transferring or translating such models to new application scenarios is often not straightforward. A typical question to answer would be how the curve characteristics are expected to change in the new situation. However, if the model explicitly considers the crucial physiologic and mechanistic aspects, and it is known from independent experiments how these change in certain scenarios, a translation and prediction can become feasible. The level of mechanistic detail needed depends on the particular problem. In certain cases, the desired detail might include sophisticated reaction networks. Sometimes, these are sufficient on their own to understand relevant PD behavior. Detailed pathway modeling is also a major activity in systems biology in academia. Many excellent reviews are devoted to this topic, which will not be further detailed here. In other cases or for other questions, the PK/PD interaction is important to consider. Here, PBPK models offer an intuitive framework for coupling PK with simple or mechanistic PD models. See \[[18](/references/references#18)] for a recent example. # Modules, Philosophy, and Building Blocks ## Introduction The Open Systems Pharmacology Suite (OSPS) contains different software tools and has been designed using a modular concept to allow efficient multi-scale modeling and simulation workflows. The ecosystem of the different software tools and their interactions is explained in the [Software Ecosystem](#software-ecosystem) section. The central software tools PK-Sim® and MoBi® make use of the building blocks concept as introduced in [PK-Sim® and its building blocks](#pk-sim) and [MoBi® and its building blocks](#mobi). PK-Sim® is based on a whole-body physiologically-based modeling concept, while the focus of MoBi® lies on modeling complex signaling pathways and extending the standard PBPK framework. The different physiological scales that are covered by the different tools are illustrated below. ![Multiscale modeling and simulation (taken from \[18\])](/files/-LNl8ZAxdbI7np6XDshV) ## PK-Sim® PK-Sim® is a comprehensive software tool for whole-body physiologically based pharmacokinetic (PBPK) modeling \[[92](/references/references#92)]. It enables rapid access to all relevant anatomical and physiological parameters for humans and common laboratory animals (mouse, rat, minipig, dog, monkey, and rabbit) contained in the integrated database. Users can access different PBPK calculation methods for fast and efficient model building and parameterization. Relevant generic passive processes, such as distribution through blood flows as well as specific active processes, such as metabolization by a particular enzyme, are automatically taken into account by PK-Sim®. Like most PBPK modeling tools, PK-Sim® is designed for use by non-modeling experts and only allows for minor structural model modifications. Unlike most PBPK modeling tools, though, PK-Sim® offers different model structures to choose from, e.g., to account for important differences between small and large molecules (see [Model settings](/working-with-pk-sim/pk-sim-documentation/pk-sim-simulations#model-settings)). More importantly, PK-Sim® is accompanied by the expert modeling software tool MoBi®, allowing full access and transparency to all model details, including the option for extensive model modifications and extensions. This way, customized systems pharmacology models may be set up to deal with the challenges of modern drug research and development. PK-Sim® applies the building blocks concept, separating information used for model building into groups: Individuals, Populations, Compounds, Formulations, Administration Protocols, Events, Observers, and Observed Data. The different building blocks are described in detail in “Working with PK-Sim®”. Building blocks from these groups are combined to generate a model. The advantage of building blocks is that they can be reused and combined to create different models. For example, after establishing a drug model after single-dose intravenous administration to an animal species, substitute the individual with a suitably parameterized virtual human population and obtain a first-in-man simulation model. Further substitute the formulation to get a controlled-release per oral simulation model, substitute the protocol to obtain a multiple dose simulation model, or replace the compound to obtain a simulation model for another drug. PK-Sim® will be described in detail in [Working with PK-Sim®](/working-with-pk-sim/pk-sim-documentation/pk-sim-quick-guide). ## MoBi® MoBi® is a systems biology software tool for multiscale physiological modeling and simulation. Within the restrictions of ordinary differential equations, almost any kind of (biological) model can be imported or set up from scratch. Examples include biochemical reaction networks, compartmental disease progression models, or PBPK models. However, de novo development of a PBPK model, for example, is very cumbersome, such that the preferred procedure is to import them from PK-Sim®. Importantly, MoBi® also allows for the combination of the described examples and thereby is a very powerful tool for modeling and simulation of multi-scale physiological systems covering molecular details and whole-body architecture. De novo model establishment and simulation are supported by graphical tools and building blocks to support expert users. MoBi® uses building blocks that are grouped into Molecules, Reactions, Spatial Structures, Passive Transports, Observers, Events, Molecule Start Values, Parameter Start Values, and Observed Data. The different building blocks are described in detail in [Working with MoBi®](/working-with-mobi/mobi-documentation/first-steps). Building blocks out of the above-mentioned groups can be combined to generate models. The advantage of building blocks is that they can be reused. Examples: * a different set of starting values may define a new scenario, situation, or individual. * refine a Reaction(s) network and update it in all tissues where it should be considered. All building blocks are further organized into **modules**. The modules are either full-scale PBPK models imported from PK-Sim, or extensions to the default PBPK structure, effect models, or any model customization. The modules are combined into **simulations**, allowing for flexible and efficient model development and simulation. MoBi® will be described in detail in [Working with MoBi®](/working-with-mobi/mobi-documentation/first-steps). ## Software Ecosystem The software ecosystem is outlined in the figure below. Apart from the two central, graphical user interface (GUI)- based software tools PK-Sim® and MoBi®, the software platform is supported by an ecosystem of various R packages, including a qualification framework, validation and automation tools, and specialized workflows for modeling and simulation. ![The software ecosystem](https://raw.githubusercontent.com/Open-Systems-Pharmacology/Suite/refs/heads/develop/OSP_software_landscape.svg) ### Qualification framework The qualification framework enables automated validation of various scenarios (use cases) supported by the OSP platform. This technical framework is used, for example, to release a new version of the OSP Suite in full confidence by automatically verifying that an ever-growing list of scenarios is performing as expected. The qualification framework will be described in detail in [Qualification](/shared-tools-and-example-workflows/qualification). ### Validation and automation tools Validation and automation tools include, for example: * **Installation Validator**: enables "1-Click" validation of the OSP Suite installation on a target computer. The validation is performed by execution of the predefined set of simulation scenarios and comparison of the simulated results with the (validated) reference values. * **Command Line Interface** (*CLI*): allows batch processing of multiple projects in PK-Sim and is described in [Command Line Interface - CLI](/working-with-pk-sim/pk-sim-documentation/pk-sim-command-line-interface). ### R-packages The OSP software suite provides a set of packages for the R computing environment that allow scripted workflows with the models developed in PK-Sim® and MoBi®. * [ospsuite](https://github.com/Open-Systems-Pharmacology/OSPSuite-R) package provides the functionality of loading, manipulating, and simulating the simulations created in PK-Sim® and MoBi®. It also offers extended workflows such as parameter sensitivity or PK-parameter calculation. The package is described in detail in [R documentation](/working-with-r/introduction-ospsuite-r). * [tlf](https://github.com/Open-Systems-Pharmacology/TLF-Library) package offers a set of functions and methods for creating standardized reporting **T**ables, **L**istings, and **F**igures. * [ospsuite.reportingengine](https://github.com/Open-Systems-Pharmacology/OSPSuite.ReportingEngine) for automated generating of model reports. * [ospsuite.parameteridentification](https://github.com/Open-Systems-Pharmacology/OSPSuite.ParameterIdentification) provides the functionality of performing parameter identification (i.e., fitting the model to observed data) with simulations. The package is currently under development and everyone is encouraged to contribute. {% hint style="info" %} OSP Qualification Framework and R packages are not included into the main OSP Suite setup and must be installed separately. Installation instructions are provided in the documentation of the tools or on the GitHub download site. {% endhint %} ### OSP Model exchange format Models created in PK-Sim® or MoBi® can be exported in *PK Modeling Language* (\***.pkml**) format and shared between the OSP tools. Internally, the PKML file format is an XML format with a predefined structure. ### Import and Export Apart from the communication and exchange via R, PK-Sim® and MoBi® have import and export functions for MS Excel®, CSV, and NONMEM® that allow for the import of experimental data or the export of simulation results, for example. MoBi® has SBML import functionalities. PK-Sim can also import and export *project snapshots* in [JSON format](https://en.wikipedia.org/wiki/JSON) (s. [Exporting Project to Snapshot](/working-with-pk-sim/pk-sim-documentation/importing-exporting-project-data-models#exporting-project-to-snapshot--loading-project-from-snapshot) for details). # Getting Started ## Software and Hardware Requirements | OS | Windows 10®, Windows 11®, Windows Server 2019®, Windows Server 2022®, Windows Server 2025® | | ---------- | ------------------------------------------------------------------------------------------ | | Processor | minimum 1 GHz (the faster, the better) | | Memory | 2 GB RAM, 4+ GB recommended | | Disk space | minimum 2 GB | | | **Optional software** | | R® | version 4.1 or higher - 64bit | The information provided above refers to the core components of the Open Systems Pharmacology Suite, including PK-Sim® MoBi®. Both PK-Sim® and MoBi® can be installed as stand-alone software packages to reduce the disk space required. {% hint style="warning" %} The Open Systems Pharmacology Suite includes interfaces to MS Excel® and R. These are separate programs that are not available within the Open Systems Pharmacology Suite. You need to have these programs installed to use their interfaces! {% endhint %} ### Trademark Information Excel® is a registered trademark of Microsoft Inc., Redmond, USA; R is a product of the R Foundation for Statistical Computing, Vienna, Austria. ## Installation and Update ### Core Components {% hint style="warning" %} To correctly install the software, administrator rights are necessary. If you do not have these rights, your IT administrator should carry out the installation. {% endhint %} {% hint style="info" %} The modular structure of the Open Systems Pharmacology Suite is explained in [Modules, Philosophy, and Building Blocks](/open-systems-pharmacology-suite/modules-philsophy-building-blocks). Both PK-Sim® and MoBi® can be installed as stand-alone applications. However, to obtain the full modeling and simulation capabilities, we recommend that both programs are installed. {% endhint %} To install the Open Systems Pharmacology Suite core components: 1. Download installation packages from . 2. Start the **OSPSuite-Full.X.Y.Z.exe**\* (where X.Y.Z is a program version, e.g. 12.0.397) from the menu Start -> Run or from Windows Explorer. 3. Follow the instructions of the installation program. In most cases, the installation should be carried out with the default settings. 4. In most cases, you will have to restart your computer following installation. 5. Download PK-Sim® [gene expression databases](https://github.com/Open-Systems-Pharmacology/Gene-Expression-Databases/releases) and copy them to a folder accessible for all users. 6. Configure PK-Sim® gene expression databases (for details, see [PK-Sim® - Options](/working-with-pk-sim/pk-sim-documentation/pk-sim-options)). ### (Re-)Qualification Framework Optional OSP Suite components which are only required for the [creation of qualification reports](https://docs.open-systems-pharmacology.org/shared-tools-and-example-workflows/qualification). Installation instructions are provided [here](https://docs.open-systems-pharmacology.org/shared-tools-and-example-workflows/qualification#tools). ### Third Party Tools In addition to the core components of the Open Systems Pharmacology Suite, including PK-Sim® MoBi®, interfaces are available for MS Excel®, Matlab®, and R. For purchasing and installation options, please contact the suppliers indicated in the section “Trademark information.” ## Help: Contact, Discussion Forum, Bug Reporting, ... Additional information on the software is available on . For support, bug reports, etc., please contact . # PK-Sim Documentation # Quick Guide Here, only the basic steps needed to work with a PBPK simulation in PK-Sim® are briefly described (creation of a model, comparison of simulation data to observed data, and refinement of the model): ![Image](/files/-LOWQ5-8kgijoOfDVpjf) ![Image](/files/-LOWQ5-GsDyNlfi_U9Zo) ![Image](/files/-LOWQ5-LQv14f4uR5zMX) ![Image](/files/-LOWQ5-PSSKwEhTLzjBK) ![Image](/files/-LOWQ5-SS1dKfATFa9_R) ![Image](/files/-LOWQ5-U36dEfn61MbaQ) # Options PK-Sim® can be customized using several options. To do this, click on the **Options** Button within the **Utilities** Ribbon Tab. ## **General** Tab ### Numerical Properties * **Allows scientific notation**: You can specify if parameter values and results are displayed in scientific notation and if they are very small or large. * **Decimal place**: You can specify the number of decimal places displayed for parameter values and results. * **Absolute tolerance** and **Relative tolerance**: You can specify the absolute and relative tolerance to control the error of the ODE solver. Changes will only affect simulations that are created after changing values. * **Maximum number of processors to use** for tasks that can be executed in parallel (population simulations, parameter identification, parallel execution of simulations). * **Number of bins**: number of bins to display in histograms of populations/population simulations for parameter distribution. {% hint style="warning" %} Setting tolerances higher than the default values (absolute tolerance: 1.0E-10; relative tolerance: 1.0E-5) may reduce simulation time but cause convergence errors. {% endhint %} ### Look and Feel * **Active skin**: The program's graphical appearance can be changed by changing the skin in the Skins group next to the Options icon. * **Number of recent file items shown**: Changes the number of recent documents displayed within the File Tab. The program needs to be restarted for the changes to take effect. * **Preferred view layout**: Choose from either tabbed or accordion view, e.g., the Compound window. * **Restore opened view when loading project**: Open tabs (e.g., particular simulations, individuals, or compounds) are saved upon saving and restored when re-opening the project. Warning—this may significantly impact a project's loading time! * **Show software update notification if available**: When enabled and connected to the internet, a check for new versions of PK-Sim® is done automatically. ### Defaults * **Species** and **Population**: Changes the default species and default population used for the creation of a new individual or population. * **Parameter layout**: Changes the default parameter layout used for parameters shown within the Anatomy & Physiology tab of an individual and the Parameters tab of a simulation. * **Lipophilicity**, **Fraction unbound,** and **Solubility**: You can specify the defaults for the description used for the Experiment input box when a new compound is created. * **Population analysis**: After the first simulation run, an analysis window opens automatically. This option sets the default type of this first analysis ('Time Profile', 'Box Whisker', ...). * **Chart y scale**: Default scaling (lin or log) of the y axis in new time-profile charts. ### Icon Sizes You can change the size of the icons displayed within the **Tree view**, the **Tabs,** and the **Context menu** ### Template Database * **Template database path:** The path to the template database. You can create a new template database by clicking on * **Load metabolites when loading compound:** Choose whether or not to load the metabolites of a compound when loading a (parent) compound. ### Colors * **Formula parameter**: Changes the background color for parameters that are calculated by a formula. * **Parameter changed**: Changes the background color for formula-calculated parameters that have been changed by the user. * **Chart background** and **Chart diagram background**: Changes the chart colors. For simulation charts, this is the default if no other color is specified in the Chart Editor of the Results Tab. * **Color group observed data from same folder when dropping to chart**: If enabled, when adding observed data sets to a chart via drag-and-drop from a folder (or multiple folders) within the "Observed Data" group, all data sets within one folder will get the same color. ## **Application** Tab * **MoBi Executable Path**: Path to the location of the MoBi.exe file Specify the path to a species-specific **Expression Database** you would like to use by clicking on the three dots in the **Expression Database** column in the row of the species you require. ![Linking a species-specific expression database to an individual.](/files/-LOWQ4xemjDdWWTX5H9Y) The available expression databases can be downloaded from the [gene expression databases repository](https://github.com/Open-Systems-Pharmacology/Gene-Expression-Databases/releases). # Projects The organization of simulations is supported by PK-Sim® with a building block concept. Each project contains a **Building Blocks** panel that comprises one or several building blocks for individuals, populations, compounds, formulations, protocols, events and observed data. Simulations that are created with the building blocks and comparisons of simulations are organized in a separate panel. The user can create subfolders for organization of observed data, simulations and comparison. {% hint style="info" %} Only one project can be opened at a time in one PK-Sim® instance. If you wish to work on more than one project in parallel you may start separate instances of PK-Sim® for each individual project. If the identical project is already being accessed by yourself or by another user, PK-Sim® will warn you and open the project as read-only. You will still be able to use the project but won't be able to save your changes. {% endhint %} The following table gives an overview on how to manage projects using the **File** tab: | Function, Icon | Shortcut | Description | | ---------------------------------------------------------------------------------------------------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | |

Create a new project

| Ctrl+N | A new project is generated. The current project is closed. If you have not saved the current project yet, you will be asked if you want to do so. If you answer Yes, all data belonging to the current project are saved using the current file-name. If the project/file name is undefined, a dialog window will open for you to specify the project name. | |

Open an existing project

| Ctrl+O |

Select the \*.pksim5 file you want to open.
• Only one project can be opened at a time. If a project is already open, you are asked if the currently open project should be saved before closing.
• If you wish to work on more than one project in parallel, you may start separate instances of PK-Sim® for each individual project.

| |

Close the project

| | The project is closed. If you have not yet saved the current project, you are asked if you want to do so. If you answer Yes, all data belonging to the project are saved using the current file-name. If the project/ file name is undefined, a will open for you to specify the project name. A new project can then be created, subsequently. | |

Save the project

| Ctrl+S | You can save your project by either selecting Save or Save as. | |

Show or edit project description

| Ctrl+D | You can enter, show or change a description for the project. | |

Export project to snapshot

| |

Export current project to snapshot.
S. Exporting Project to Snapshot / Loading Project from Snapshot for details.

| |

Load project from snapshot

| |

Create a new project from snapshot.
S. Exporting Project to Snapshot / Loading Project from Snapshot for details.

| |

Select Journal

| |

Assign a working journal to the current project.
S. Shared Tools - Working Journal for details.

| |

About this application

| | An overview of the PK-Sim® version information is given. | |

Exit the application

| Alt+F4 | PK-Sim® is closed. If you have not yet saved the current project, you are asked if you want to do so. If you answer Yes, all data belonging to the project are saved using the current file-name. If the project name is undefined, a dialog window will open for you to specify the project name. | The visualization of a project is organized in different panels. Each panel can be hidden or be made visible by clicking on the respective icon in the **Views** Tab. The panels have the following meaning: | Panel, Icon | Description | | ------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | |

Building Blocks

|

Within this panel the building blocks Expression Profiles, Individuals, Populations, Compounds, Formulations, Administration Protocols, Events, Observers, and Observed Data are organized and can be accessed. Detailed information for each building block can be found in:
● PK-Sim® - Expression Profiles
● PK-Sim® - Creating Individuals
● PK-Sim® - Creating Populations
● PK-Sim®- Compounds: Definition and Work Flows
● PK-Sim® - Formulations
● PK-Sim® - Administration Protocols
● PK-Sim® - Events
● Shared Tools - Import and Edit of Observed Data.

| |

Simulations

|

In this panel all simulations of a project are managed. A detailed description on how simulations are set up and managed can be found in PK-Sim® - Simulations.
Besides simulations, this panel contains the following objects:
● Simulation comparisons (s. PK-Sim® - Simulations: Comparison charts for details)
● Parameter Identifications (s. Shared Tools - Parameter Identification for details)
● Sensitivity Analyses (s. Shared Tools - Sensitivity Analysis for details)

| |

History Manager

| Every user action performed within a given project work is documented within this panel. Features of the History Manager are described in [Shared Tools - History manager and history reporting](/shared-tools-and-example-workflows/history-manager-history-reporting). | |

Comparison

|

Shows comparison results of 2 building blocks or 2 simulations.
S. Shared Tools - Comparison of Building Blocks for details.

| |

Working Journal

|

Shows the working journal of the current project.
S. Shared Tools - Working Journal for details.

| |

Working Journal Diagram

|

Shows the working journal of the current project.
S. Shared Tools - Working Journal for details.

| # Expression Profile ## Background: Active Processes in PK-SIM ### The role of proteins in PBPK modeling Small molecules frequently interact with proteins. Protein/compound interaction may influence all aspects of ADME to a varying extent. Metabolic and transport processes are of particular importance in this context. Most protein concentrations vary spatially as well as temporally. PK-Sim® allows the user to model proteins and compound/protein interactions. Active, protein-mediated processes involved in drug ADME generally occur simultaneously in various organs. However, a quantitative description of active processes is difficult due to the limited experimental accessibility of tissue-specific protein activity in vivo. PK-Sim® uses gene expression data as a surrogate for protein abundance to estimate in vivo activity of such enzymes or transporters that influence drug pharmacokinetics. This concept implies that protein availability and catalytic rate constants, which ultimately underlie enzyme and transporter activity, are decoupled. For more details, please see \[[46](/references/references#46)]. In brief, the concept of using gene expression data as a proxy for protein abundance is based on the definition of the maximum velocity *Vmax* \[µmol/l/min]. According to the Michaelis-Menten equation, *Vmax* depends on both the total enzyme or transporter concentration E0 \[µmol/l] and the catalytic rate constant *kcat* \[1/min]: ![Equation 1](/files/-LNl8Wite45sol22HItW) Assuming that kcat is not influenced by in vivo factors, the tissue-specific maximum velocity *Vmax,organ* is defined as: ![Equation 2](/files/-LNl8WiwxYLHdRZLDqOP) ### Protein expression profile Following **Equation 2**, the effective rate of a protein-mediated process, be it metabolization, transport, or binding reaction, directly depends on the total amount of the protein in the respective compartment. The abundance of proteins in different organs in PK-Sim is calculated from **relative expression** values. For each organ, the relative expression defines the protein concentration in the whole organ as a fraction of a defined **reference concentration** value. ![Protein expression profile overview](/files/z4tNjpb2i5uMzTj6CZPi) ### Reference concentration The **reference concentration** can be measured in vitro, allowing direct in vitro - in vivo extrapolation (IVIVE). The protein concentration in the organ with the **relative expression = 1** will equal that measured concentration. The concentrations in all other organs will be set relative to that value. If no in vitro protein abundance values are available for any organ, the reference concentration can be set to any arbitrary value (the default value is 1 µmol/L). While direct IVIVE will not be possible in this case, the model will still be able to account for the different contributions of the organs to the total process rate (e.g., metabolism of a compound) through the relative expressions. For example, the enzyme **CYP3A4** is mainly expressed in the liver of human adults, some in the gastrointestinal tract, and minor amounts in almost all other tissues. The concentration of CYP3A4 in the liver is 108 pmol/mg microsomal protein \[[63](/references/references#63)]. The concentration of microsomal protein in the liver is 40 mg per g liver. Assuming a specific tissue density of 1 g/mL, the concentration of CYP3A4 in whole liver is 4.32 µmol/L. This number can be used as a reference concentration with a relative expression of 1 in the liver. The following table shows reference concentrations from a selection of CYP enzymes. The values were derived from measurements of human microsomal samples, see \[[63](/references/references#63)]. Table: Reference concentration of CYP enzymes | Enzyme | pmol/mg human liver microsomes | µmol CYP/L liver tissue (Reference concentration) | | ------- | ------------------------------ | ------------------------------------------------- | | CYP1A2 | 45 | 1.8 | | CYP2A6 | 68 | 2.72 | | CYP2B6 | 39 | 1.56 | | CYP2C18 | <2.5 | <0.1 | | CYP2C19 | 19 | 0.76 | | CYP2C8 | 64 | 2.56 | | CYP2C9 | 96 | 3.84 | | CYP2D6 | 10 | 0.4 | | CYP2E1 | 49 | 1.96 | | CYP3A4 | 108 | 4.32 | | CYP3A5 | 1 | 0.04 | Special attention has to be paid when using ontogeny information together with the reference concentration. The reference concentration is subject to an age-dependent ontogeny, and the underlying implementation assumes that the reference concentration refers to an ontogeny factor of 1. For example, if it is known that for a 0.5-year-old individual, the ontogeny factor of a particular enzyme is 0.1, and the concentration of the enzyme in individuals of that age is 0.13 µmol/ L, the reference concentration (of an adult) is 1.3 µmol/L (that is 0.13/0.1). PK-Sim® supports different protein expression databases that must be configured in the PK-Sim® options, see [Options](/working-with-pk-sim/pk-sim-documentation/pk-sim-options). As of August 2025, all models within the official [OSP PBPK Model Library](https://github.com/Open-Systems-Pharmacology/OSP-PBPK-Model-Library/releases/tag/v12.0) are built with the large-scale human gene-expression [database Version 2](https://github.com/Open-Systems-Pharmacology/Gene-Expression-Databases/releases/tag/v2.0.0). This database was compiled from publicly available sources that were downloaded, processed, stored and customized to be directly utilized in PBPK model building \[[63](/references/references#63)]. The public databases that were imported are * whole genome expression arrays from ArrayExpress (ArrayExpress, 2010) * RT-PCR-derived gene expression estimates from literature \[[49](/references/references#49)], \[[50](/references/references#50)], \[[51](/references/references#51)] * Expressed sequence tags (EST) from UniGene. The consolidated expression data was stored in a database with three sections: EST (UniGene), Array (ArrayExpress), and RT-PCR (literature cited above). A new [database Version 3](https://github.com/Open-Systems-Pharmacology/Gene-Expression-Databases/releases/tag/v3.0.1) containing expression profiles for various species, including humans, has been generated from the [Bgee](https://www.bgee.org/) database. It should be noted that the current databases only describe the spatial distribution of active processes in PBPK models. Temporal aspects such as circadian rhythms underlying chronogenetics are not included. If necessary, such effects may be considered in a corresponding MoBi® model. ### The cellular and tissue-specific location of active proteins Proteins involved in the metabolism or transport of compounds are located in different organ sub-compartments. While enzymes usually reside inside organ cells, transport proteins are located in membranes. Another important feature of biological cells that has to be considered is polarity. Organs containing epithelial cell membranes, like intestinal mucosa, liver (bile duct epithelium), and kidney (tubular epithelium), express different types of proteins on either side of the cell, whether basolateral or apical. The apical membrane is exposed to the luminal space, while the basolateral membrane faces the interstitial space of the tissue. The *relative expression* defines the concentration of the protein in the whole organ, i.e., the sum volume of the sub-compartments interstitial space, intracellular space, blood plasma and blood cells, and (for the large molecules model) the endosomal space. Within the organ, the protein can be distributed over the different sub-compartments, with the *effective concentration* in the compartment being calculated by PK-Sim such that the concentration in the whole organ ![Effective protein concentration](/files/-MczYzD1HmK0stBUVDKj) is ![Effective protein concentration](/files/-MczYzD3n9w6f_kAEIIY) with ***RC*** being the reference concentration and ![RelExp\_Org](/files/-MczYzD5Obl72-n0v29c) the relative expression in this organ. The following sections give an overview over the possible localizations and the equations used to calculate the effective concentrations in the different compartments for enzymes and transport proteins. ### Localizations and initial concentrations of enzymes ![Localization Enzymes](/files/DCjTG5bftNyH3NhwGp9F) By default, an added enzyme is localized only in the intracellular space of the organs. The user can select additional compartments where the enzyme should be expressed and set the expression values. * **Plasma**: Enzymes floating in blood plasma. The specified relative expression will be added to the enzyme's expression in every organ's plasma compartment. * **Blood Cells**: Enzymes expressed in blood cells of all organs; the specified relative expression refers to blood cell volume. These enzymes can be located within blood cells or the cell membrane, facing the blood plasma. The relative distribution of the enzyme between the cellular space and the plasma membrane is defined by the parameters: * “*Fraction expressed in blood cells*” defines the amount of protein within the cell and acts on the educts located in the cell, * “*Fraction expressed in blood cell membrane*” is added to the expression in plasma and acts on the educts located in blood plasma. * **Vascular endothelium**: Enzymes expressed in arteries, veins, and capillaries. The relative expression refers to the volume of the vascular endothelium of the organ. Due to the specificity of implementation in PK-Sim, vascular endothelium is not explicitly modeled in the organs “Arterial Blood”, “Venous Blood”, and “Portal Vein”. * “*Fraction expressed in endosome*”: The enzyme is located in the endosomes of the vasculature. Please keep in mind that the endosomal compartment is not present in the model for small molecules. * “*Fraction expressed on plasma-side membrane of vascular endothelium*”: the enzyme is located in the membrane of endothelial cells facing blood plasma and acts on educts in plasma. The fraction of the relative expression is added to the expression in plasma. * “*Fraction expressed on tissue-side membrane of vascular endothelium*”: the enzyme is located in the membrane of endothelial cells facing the interstitial space and acts on educts in the interstitial space of the organ. The fraction of the relative expression is added to the expression in interstitial space. {% hint style="info" %} The relative expressions (and the fractions expressed at different sites) of the enzyme in the vascular system are equal for all organs. {% endhint %} * **Tissue**: The expression values for the organ tissue (excluding the vascular system) can be defined per organ and refer to the amount of the protein in whole organ (including plasma and blood cells). The “*Fraction expressed intracellular*” defines the concentration of the enzyme located intracellularly as fraction of total amount and acts on educts located intracellularly. The “*Fraction expressed interstitial*” defines the amount of the enzyme that is available in the interstitial space. Usually this refers to the enzymes located in the cellular membrane facing the interstitial space. NOTE: As per construction, it’s always `Fraction expressed interstitial = 1 - Fraction expressed intracellular` **Initial concentrations** of the enzymes in the different compartments within the model are combined from the relative expression values of organs having direct access to this compartment. The name “initial concentration” refers to the fact that these concentrations may change during simulation course e.g. through mechanism based inactivation. The concentration of the enzyme in the compartment ultimately defines the rate of the reaction catalyzed by this enzyme. {% hint style="info" %} The initial concentration value will be effectively calculated when the expression profile is linked to an individual e.g. when individual specific parameters such as volumes, hematocrit etc... are defined {% endhint %} To set a specific initial concentration value in a given compartment, simply overwrite the value in the expression profile for this specific compartment. This will effectively ensure that all individual using the expression profile will use the same initial concentration. {% hint style="warning" %} Do only overwrite initial concentration by hand if absolutely required. {% endhint %} * **BloodCells:** `RC * rel_exp_bc * f_exp_bc_cell` * *RC*: Reference concentration * *rel\_exp\_bc*: Relative expression in blood cells * *f\_exp\_bc\_cell*: Fraction expressed in blood cells * **Plasma (ArterialBlood, VenousBlood, PortalVein):** Combination of the expression in plasma and in blood cells in the membrane facing plasma. `RC * (rel_exp_pls + rel_exp_bc * f_exp_bc_membrane * HCT / (1 - HCT))` * *RC*: Reference concentration * *rel\_exp\_pls*: Relative expression in plasma * *rel\_exp\_bc*: Relative expression in blood cells * *f\_exp\_bc\_membrane*: Fraction expressed in blood cells membrane * *HCT*: Hematocrit * **Plasma (in organs except for ArterialBlood, VenousBlood, PortalVein):** Combination of the expression in plasma, in blood cells in the membrane facing plasma, and in vascular endothelium in the membrane facing plasma. `RC * (rel_exp_pls + rel_exp_bc * f_exp_bc_membrane * HCT / (1 - HCT) + rel_exp_vasend * f_exp_vasend_apical * V_vasend / V_pls)` * *RC*: Reference concentration * *rel\_exp\_pls*: Relative expression in plasma * *rel\_exp\_bc*: Relative expression in blood cells * *f\_exp\_bc\_membrane*: Fraction expressed in blood cells membrane * *HCT*: Hematocrit * *rel\_exp\_vasend*: Relative expression in vascular endothelium * *f\_exp\_vasend\_plasma*: Fraction expressed on membrane of vascular endothelium facing blood plasma * *V\_vasend*: Volume (endothelium) * *V\_pls*: Volume plasma * **Interstitial:** Combination of the expression in organ and in vascular endothelium in the membrane facing interstitial space. Be aware that depending on how the expression values for the organs have been obtained, explicit addition of the expression in vascular endothelium may result in higher calculated effective concentration. `RC * (rel_exp_org * f_exp_org_int * 1 / f_int + rel_exp_vasend * f_exp_vasend_tissue * V_vasend / V_int)` * *RC*: Reference concentration * *rel\_exp\_org*: Relative expression in organ * *f\_exp\_org\_int*: Fraction expressed interstitial * *f\_int*: Fraction interstitial (of total organ volume) * *rel\_exp\_vasend*: Relative expression in vascular endothelium * *f\_exp\_vasend\_tissue*: Fraction expressed on membrane of vascular endothelium facing tissue * *V\_vasend*: Volume (endothelium) * *V\_int*: Volume (organ interstitial) * **Intracellular:** `RC * rel_exp_org * f_exp_org_cell * 1 / f_cell` * *RC*: Reference concentration * *rel\_exp\_org*: Relative expression in organ * *f\_exp\_org\_cell*: Fraction expressed intracellular * *f\_cell*: Fraction intracellular(of total organ volume) * **Endosome:** `RC * rel_exp_vasend * f_exp_vasend_endosomes * 1 / f_endo` * *RC*: Reference concentration * *rel\_exp\_vasend*: Relative expression in vascular endothelium * *f\_exp\_vasend\_endosomes*: Fraction expressed in endosomes * *f\_endo*: Fraction endosomal (of total organ volume) ### Localizations, directions, and initial concentrations of transport proteins ![Localization Transporter](/files/GGzjNPlPIpJTB9j5zkti) Transporters are located in the cell membranes, connecting two neighbor compartments. Four transport directions can be specified: * **Influx**: The substance is transported from the interstitial space or lumen to the intracellular space. * **Efflux**: The substance is transported from intracellular space to interstitial space or lumen. * **Bi-directional**: Facilitated transport along the concentration gradient. It is assumed that Vmax and Km values are equal for both directions. Only Michaelis-Menten kinetics can be used with this direction. * **Plasma to interstitial space** across endothelial border * **Interstitial space to plasma** across endothelial border As the model structure of PK-Sim does not explicitly contains membranes, expression of transporters is modeled in one of the neighbor compartments. In addition to the default transporter direction that is applied for all compartments, the direction can be specified for each compartment separately. As for proteins, the relative expression of a transport protein in an organ refers to the volume of organ tissue without blood cells and blood plasma. Following localizations are available: * **Blood cells**: Transport between blood cells and plasma Initial concentration: `RC * rel_exp_bc` * *RC*: Reference concentration * *rel\_exp\_bc*: Relative expression in blood cells * **Vascular endothelium**: Transport between blood plasma and the interstitial space of all organs. The transporter is placed in blood plasma with initial concentration given by the equation `RC * rel_exp_vasend * V_vasend / V_pls` * *RC*: Reference concentration * *rel\_exp\_vasend*: Relative expression in vascular endothelium * *V\_vasend*: Volume (endothelium) * *V\_pls*: Volume of plasma {% hint style="info" %} Be aware that depending on how the expression values for the organs have been obtained, explicit addition of the expression in vascular endothelium may result in higher calculated effective amount of the protein in tissue. {% endhint %} * **Organs**: In organs that do not have a lumen (bone, fat, gonads, heart, lung, muscle, pancreas, skin, spleen, stomach, and non-mucosal small and large intestine), with the exception of brain, transport proteins are always modeled in the interstitial space, transporting the molecules between intracellular and interstitial spaces. The initial concentration is given by the equation `RC * rel_exp_org * 1 / f_int` * *RC*: Reference concentration * *rel\_exp\_org*: Relative expression in organ * *f\_int*: Fraction interstitial (of total organ volume) * **Brain**: Transporter proteins in brain tissue are usually located in endothelial cells, transporting molecules across the blood-brain-barrier. This distinct nature of the brain tissue is captured in PK-Sim by locating the transport proteins by default into plasma compartment for the transport between plasma and interstitial space. The user can enforce expression of the transporter in interstitial compartment for the transport between interstitial and intracellular by setting the “Fraction expressed at blood brain barrier” and “Fraction expressed in brain tissue”. The concentrations in the respective compartments are calculated such that the total concentration in brain is `RC * rel_exp_org`. * The concentration in **plasma** is given by the equation `RC * rel_exp_brn * f_exp_brn_bbb * 1 / (f_vas * (1 - HCT))` * *RC*: Reference concentration * *rel\_exp\_brn*: Relative expression in brain * *f\_exp\_brn\_bbb*: Fraction expressed at blood brain barrier * *f\_vas*: Fraction vascular (of total organ volume) * *HCT*: Hematocrit * The concentration in **interstitial space** is given by the equation `RC * rel_exp_brn * f_exp_brn_tissue * 1 / f_int` * *RC*: Reference concentration * *rel\_exp\_brn*: Relative expression in brain * *f\_int*: Fraction interstitial * **Kidney** and **Liver**: In kidney and liver, transport proteins can be located between interstitial and intracellular spaces (defined by “Fraction expressed basolateral” and modeled in interstitial space) and/or on the apical site of renal tubule and hepatic bile duct cells (defined by “Fraction expressed apical” and modeled in intracellular space), respectively. Transporters located on the apical site are responsible for active excretion of the compounds into urine and bile in kidney and liver, respectively. * Initial concentration in **interstitial space** is given by the equation `RC * rel_exp_org * f_exp_org_basolatateral * 1 / f_int` * *RC*: Reference concentration * *rel\_exp\_org*: Relative expression in organ * *f\_exp\_org\_basolatateral*: Fraction expressed on the membrane between cellular and interstitial spaces * *f\_int*: Fraction interstitial (of total organ volume) * Initial concentration in **intracellular space** is given by the equation `RC * rel_exp_org * f_exp_org_apical * 1 / f_cell` * *RC*: Reference concentration * *rel\_exp\_org*: Relative expression in apical * *f\_exp\_org\_apical*: Fraction expressed on epithelial membrane * *f\_cell*: Fraction intracellular (of total organ volume) * **Mucosal tissue**: The apical site of mucosal cells is facing the gastrointestinal lumen and facilitates the absorption or active excretion, while the basolateral site connects the intracellular and interstitial spaces. * Initial concentration in **interstitial space** is given by the equation `RC * rel_exp_org * f_exp_org_basolatateral * 1 / f_int` * *RC*: Reference concentration * *rel\_exp\_org*: Relative expression in organ * *f\_exp\_org\_basolatateral*: Fraction expressed on the membrane between cellular and interstitial spaces * *f\_int*: Fraction interstitial (of total organ volume) * Initial concentration in **intracellular space** is given by the equation `RC * rel_exp_org * f_exp_org_apical * 1 / f_cell` * *RC*: Reference concentration * *rel\_exp\_org*: Relative expression in apical * *f\_exp\_org\_apical*: Fraction expressed on epithelial membrane * *f\_cell*: Fraction intracellular (of total organ volume) ## The workflow If you want to use the gene expression databases, ensure that they are correctly installed and linked to the application, see [Options](/working-with-pk-sim/pk-sim-documentation/pk-sim-options). The workflow of integrating protein data with PBPK models comprises the following steps: 1. Identification of relevant metabolizing enzymes, transport proteins, and protein binding partners for the compound of interest (*your internal research or literature*) 2. Determination of organ and tissue specific distribution of protein concentrations (PK-Sim® supports this task with a built-in database) 3. Identification of cellular location of proteins (*your internal research or literature*) 4. Devise applicable kinetics and adjust kinetic parameters (*modeling, your internal research or literature*) ## Modeling protein/drug interactions in PK-Sim® The distribution of a protein (metabolizing enzyme, transporter protein, or a protein binding partner) in the modeled organism is defined by an Expression Profile in the "Expression Profiles" building block. The expression profile is then linked to the individual (see [PK-Sim® Creating Individuals](/working-with-pk-sim/pk-sim-documentation/pk-sim-creating-individuals)), and the interaction between the protein (e.g., a metabolization reaction) is defined in the "Compounds" building block, see [PK-Sim® Compounds: Definition and Work Flows](/working-with-pk-sim/pk-sim-documentation/pk-sim-compounds-definition-and-work-flow). ## Definition of new Expression Profile in PK-Sim® To create a new expression profile, do one of the following: * Click **Expression Profile** in the **Create** Group of the **Modeling** Tab and select the protein type (metabolizing enzyme, transport protein, or protein binding partner) * Right mouse click on **Expression Profiles** in the **Building Block Explorer** and select **Add Expression Profile...** The following dialog will open in which the properties of the expression profile can defined: ![Create Expression Profile (for a metabolizing enzyme)](/files/tAWXPPJGVzEAuk386m1b) * **Species**: Species for which the expression profile will be defined. Note: The profile can only be added to an individual with the same species! You need to create separate expression profiles for each species where the protein should be used. * **Metabolizing Enzyme**: Name of the enzyme. You can select from a predefined list of common proteins or enter a name * **Phenotype**: A free text allowing you to specify the expression profile. For example, you might want to create different profiles for the CYP3A4 enzyme in human for poor vs extensive metabolizer. In this case, **poor** and **extensive** could be used. Alternatively, you might want to create a profile for a **healthy** vs **sick** individual etc... {% hint style="info" %} The combination {Species, Protein, Phenotype} needs to be unique in the project. It will define the name of the expression profile building block {% endhint %} ## Editing an Expression Profile in PK-Sim® There are two ways of editing an expression profile, either via a database query using the PK-Sim® gene expression database, or through direct entering of protein expression to a list of organs and tissues. ### Editing protein expression manually If you know expression of proteins in one or several organs you can define the expression data manually. We will explain settings in detail in [Settings in the protein expression tab](#settings-in-the-protein-expression-tab). ### Editing protein expression by querying the expression database {% hint style="info" %} To be able to query expression data from a database you have to select a database for the current species in PK-Sim ®options (see [PK-Sim® Options](/working-with-pk-sim/pk-sim-documentation/pk-sim-options)). {% endhint %} Click on **Database Query**. A database query wizard will open, using the name of the protein as a default search criteria. This is discussed in more detail in “[Advanced Analysis](#advanced-analysis)”. Here we walk you through the simplest possible process. ### Adding search criteria The first panel of the database search wizard allows you to enter a search term in the search bar ![Expression Protein Selection](/files/-LNl8Wj9qjiVOPSNJinm) This term can be anything from gene name, gene symbol, or parts of the description. {% hint style="info" %} The term is automatically enclosed by wildcards. You can turn off this default behavior by enclosing the term with “quotes”. As wildcards you can use a percent sign (%) or a star (\*) for multiple characters and a question mark (?) or underscore (\_) for a single character. {% endhint %} Once you hit enter, you will see a list of database entries that match your search. Several details are displayed like: * Gene Name * Name Type (e.g. is the gene name a synonym) * Gene symbol (this is the most authoritative naming convention) * (entrez) Gene ID * Official full name for the protein or gene Select the appropriate entry in the list of search results (or refine your search). {% hint style="info" %} The (entrez) gene ID is also a hyper link to the NCBI gene page where you can find additional information about the gene. {% endhint %} {% hint style="info" %} A hit row is highlighted in gray if the gene is known in the database but there are no expression data available. In this case the other tabs are disabled. {% endhint %} ### Reviewing measured gene expression In the upper panel you can find a table of gene expression values. The table is organized with tissues in rows, and data sources in columns. {% hint style="info" %} You can select one or several cells with the mouse (press left mouse key down), copy the content with **Ctrl+C**, and paste the values into another application, e.g. Microsoft Excel,® with **Ctrl+V**. {% endhint %} The lower panel gives a graphical representation of the gene expression values. In the table (upper panel), the data can be filtered by several criteria. (REF: How to use the database query wizard). ![Expression Data Analysis](/files/-LNl8WjBWiL0h8Y9BfLw) ### Reviewing data before transfer In the data transfer overview tab the data to be transferred are compiled for reviewing. Note, that relative expression values are given. In the upper part of the windows one or more radio buttons are displayed. The radio buttons are used to select the appropriate data source. Currently, Array, EST or RT-PCR can be selected. After selecting one of the data sources the expression levels in different PBPK containers are displayed in the lower panel. Select the most appropriate data source and click **OK** to close the database query wizard. The expression data is transferred to PK-Sim® ![Expression Data Transfer](/files/-LNl8WjDqA8i5qPFy46Q) {% hint style="info" %} The Array Database is best in terms of the number of genes covered (essentially the complete genome), RT-PCR provides the most accurate measurements, and EST data in some cases covers unusual types of tissue. Use the data sources that has the most appropriate coverage of tissues for your purpose. Array data is usually a good choice. {% endhint %} {% hint style="info" %} When using several proteins different data sources for different proteins may safely be used. {% endhint %} ![Expression Input Form With Transferred Data](/files/aTf9uVoWnCepQyliVPWg) {% hint style="info" %} The complete data set is stored within the PK-Sim® project. If you re-enter the query by selecting the **Edit...** menu item from the context menu of a defined protein, all data will be taken from the internally saved data set. To force access to the database you need to re-query the protein in the protein selection form. {% endhint %} {% hint style="info" %} You can rename a defined expression profile within your PK-Sim® project by selecting the **Rename...** menu item from the context menu of a defined expression profile. This name has no impact on the query and is only used to identify the protein within the PK-Sim® project. {% endhint %} ## Settings in the protein expression tab In the upper section, the following entries can be adjusted: * **Reference concentration**: Enter the molar concentration of the protein in the organ with the highest enzyme concentration (typically the liver). This is useful as you will later solely enter relative enzyme concentrations. If you do not know the absolute concentration in the organ with the highest expression level you can leave this entry at its default value of 1.00 μmol/mg and adjust the active process, e.g. via the Vmax value. See [Reference Concentration](#reference-concentration) for a more detailed discussion of the Reference concentration. * **t1/2 (liver)** and **t1/2 (intestine)**: Half-life of the protein turnover in the liver and in the intestine. * **Ontogeny like**: A list of typical enzymes and locations is shown for which the PK-Sim® software already knows ontogenies. Ontogenies are age-depending changes of enzyme concentrations in the respective organ or tissue. Currently, ontogeny information is only available for the liver and for the intestine and restricted to a selection of important enzymes. {% hint style="info" %} Detailed information on the integrated enzyme ontogenies is available in the separate documentation [PK-Sim® Ontogeny Database](https://github.com/Open-Systems-Pharmacology/OSPSuite.Documentation/blob/master/PK-Sim%20Ontogeny%20Database%20Version%207.3.pdf) {% endhint %} If the selected enzyme is recognised and ontogeny information is available, that enzyme is preselected. Otherwise, from this list the ontogeny of an enzyme/ protein may be selected. The button to the right of the list can be used to visualise the ontogeny. The fraction of adult protein content in a specific organ is plotted against age. The gene expression that is used in the simulation incorporates the age- dependency of the ontogeny. In the lower section, values of relative expression can be edited for individual tissues, vascular system and GIT - Lumen. Additionally: * For metabolizing enzymes and protein binding partners: * The localization in tissue, blood cells and vascular endothelium can be modified (see [Localizations and initial concentrations of enzymes](#localizations-and-initial-concentrations-of-enzymes) for explanation of the various parameters). ![](/files/-Md2M6ralj6Xiu2W2Y97) Activating/deactivating checkboxes in each of these 3 localization groups changes some parameter values and shows/hides parameters following the following logic: * If only one option in a group is activated: corresponding `fraction expressed` parameter will be set to 1; other `fraction expressed` parameter(s) of this group will be set to 0; all `fraction expressed` parameters of the group will be hidden. E.g. activating the checkboxes as in the screenshot above will result in: * **Tissue** localization parameters: * `Fraction expressed intracellular = 1` (parameter is hidden) * `Fraction expressed interstitial = 0` (parameter is hidden) * **Blood Cells** localization parameters: * `Fraction expressed in blood cells = 1` (parameter is hidden) * `Fraction expressed in blood cells membrane = 0` (parameter is hidden) * **Vascular Endothelium** localization parameters: * `Fraction expressed in endosomes = 1` (parameter is hidden) * `Fraction expressed on plasma-side membrane of vascular endothelium = 0` (parameter is hidden) * `Fraction expressed on tissue-side membrane of vascular endothelium = 0` (parameter is hidden) * If more than one option in a group is activated: corresponding `fraction expressed` parameters are shown and can be edited by user. E.g. for the selection below: ![](/files/-Md2M6rgrwK3kFhwmIog) * **Tissue** localization parameters: * `Fraction expressed intracellular` is shown and can be edited by user * `Fraction expressed interstitial` is shown (not editable; always set as `1 - Fraction expressed intracellular`) * **Blood Cells** localization parameters: * `Fraction expressed in blood cells` is shown and can be edited by user * `Fraction expressed in blood cells membrane` is shown (not editable; always set as `1 - Fraction expressed in blood cells`) * **Vascular Endothelium** localization parameters: * `Fraction expressed in endosomes` is shown and can be edited by user * `Fraction expressed on plasma-side membrane of vascular endothelium` is shown and can be edited by user * `Fraction expressed on tissue-side membrane of vascular endothelium` is hidden and always set to `1 - (Fraction expressed in endosomes + Fraction expressed on plasma-side membrane of vascular endothelium)` ![](/files/-Md2M6rkg_x9pwDfZrjX) * If all options in a group are deactivated: all corresponding `Fraction expressed` parameters are hidden AND all corresponding relative expressions are automatically set to 0. E.g. deactivating both options "*Blood cells intracellular*" and "*Blood cells membrane*" will not only hide the parameters `Fraction expressed in blood cells` and `Fraction expressed in blood cells membrane` but also set `Relative expression in blood cells` to 0 and hide it. In such a case, before setting relative expressions to zero a warning is shown to the user to avoid the loss of information: ![](/files/-Md2M6rnomhtzottt2JH) * For transport proteins: * For some organs, `Fraction expressed apical` can be set (see [Localizations, directions, and initial concentrations of transport proteins](#localizations-directions-and-initial-concentrations-of-transport-proteins) for explanation of the various parameters). * Transporter direction can be set to **Efflux**, **Influx** or **Bi-Directional**. * Transporter direction can be set **for each organ independently**. In order to change the direction in all organs simultaneously, change the selected value in the "Default Transporter Direction" selection box.

The value of the "Default Transporter Direction" is only used to reset all organ transporter directions to the given type and is not used in the model. E.g. if the user sets the default transporter direction to Efflux in all organs and then changes it to Influx in one organ: in this particular organ the Influx transporter will be created!

The transporter direction Pgp-like is, starting with version 11 of PK-Sim, marked as [DEPRECATED] and should not be used anymore. It is only available for compatibility reason with older models and will be removed in a future version of the software.

![Transporter directions](/files/-Md2M6rrgSiGfmy1M8KK) * For all proteins: * Initial concentration in every compartment (which is calculated based on the reference concentration, relative expression values and localization settings as described above) is hidden as per default. To show and **to edit** it (if required), the *Show initial concentration* checkbox must be activated:

Most initial concentration values can only be computed in the context of an individual the expression profile is linked to. If you enter a specific value, it will be used in all individuals that use this expression profile and will effectively replace the formula described previously.

![Show/Edit (effective) initial concentration](/files/-Md2M6ru8CknxrVqT6q5) ## Advanced Analysis In this section the more advanced features of the expression database integration are explained. ### Pivot Table In the upper section of the “Data Analysis tab page” the expression data is compiled in a pivot table. With the help of a pivot table cross tabulations are easily possible. You can drag fields to use them as additional row or column headers. The table changes dynamically. ![Expression Data Analysis Pivot Table](/files/-LNl8WjKGpSxJZFZIJx8) {% hint style="info" %} You can change the X-Axis field used by the corresponding chart by double clicking on a row header. This feature is only available for fields with no empty values. {% endhint %} {% hint style="info" %} You can change the series building field used by the corresponding chart by double clicking on a column header. This feature is only available for fields with no empty values. {% endhint %} {% hint style="info" %} You can reset all fields back to their default position by double clicking on a filter field header. The fields used in the chart are also reset by that action. {% endhint %} ## Filtering Data Each field can be used for filtering. To open the filter dialog click on the filter symbol ![Image](/files/-LNl8WjMZK0GirXy716L) which is shown in the field header when hovering over a field. ![Field Filter Dialog](/files/-LNl8WjOhKK9YmgREqoA) By ticking the check boxes you can toggle the filtering of individual values. {% hint style="info" %} The buttons in the upper area have the following meaning: * The ![Image](/files/-LNl8WjQ15UDSyFYbmp3) button can be used to limit the list of values to only those that are currently visible. If you would have added a filter on another field some values might are unreachable. Those values would be hidden. * The ![Image](/files/-LNl8WjSmSMGUJGTANT4) button can be used to change the check box into an option box which means that you can only select one filter value at a time and that the previously selected value gets automatically deselected by selecting a new value. * The ![Image](/files/-LNl8WjU7xbtZaPzb2AI) button can be used to invert the selected filter values which means that every selected value gets deselected and vice versa.. {% endhint %} The respective active filter is shown right under the table. ![Expression Data Analysis Pivot Table With Filter](/files/-LNl8WjWXOFRuW5Bj0_0) Click on **Edit Prefilter** to open a dialog for editing complex filter conditions. ![Prefilter Dialog](/files/-LNl8WjY2s3xjLuMO2rv) To add a condition for the age of the population used in the expression data measurements you can add a condition in the prefilter dialog with the following steps: * First save the current condition to the clipboard by selecting the topmost logical operator and pressing **Ctrl+C**. * Change the topmost logical operator to “And”. * Restore the original condition by pressing **Ctrl+V**. * Add a new condition by pressing the button behind the topmost logical operator “And”. * Select the column “Age(Minimum)” and select the condition operator “Is greater than or equal to” and enter the value “18”. Now the condition has changed and only data from adults will be used ![Prefilter Dialog With Age Condition Added](/files/-LNl8Wj_UFsRXzhDoeh7) {% hint style="info" %} For filtering age ranges of populations you might find it more convenient to use the \[Age(Minimum)] and \[Age(Maximum)] columns. {% endhint %} ### Edit Mapping A default mapping maps measured expression data of tissues to PK-Sim® containers. This mapping can be changed by users. If you double click on the value of a container or tissue the edit mapping dialog opens. ![Edit Mapping Dialog (End of List)](/files/-LNl8WjbaZgefpboixti) On the left hand side of the dialog the containers with their corresponding icons are shown and on the right hand side the currently mapped tissue is shown. Blue font means that there is no expression data available for that tissue. At the end of the list all tissues are displayed for which data could be found but which are not already mapped. ![Edit Mapping Dialog (End of List)](/files/-LNl8WjdnzNcTJ_MHEeV) It is possible to map one tissue to multiple containers. For example the Small Intestine is mapped by default to several areas of the GI tract. In the navigator panel of the edit mapping dialog, the following buttons can be used: * The ![Image](/files/-LNl8WjfgtKd0f4P9Ec-) button brings you to the first record. * The ![Image](/files/-LNl8WjhinXECdJ5Sq7Q) button brings you 10 records backwards. * The ![Image](/files/-LNl8Wjj9vUcL6kUEJ1q) button brings you to the previous record. * The record counter ( ![Image](/files/-LNl8WjlZeXljI7a81ew)) shows you the actual position and the total number of records. * The ![Image](/files/-LNl8WjngveoHhRB5iQV) button brings you to the next record. * The ![Image](/files/-LNl8WjpxYnzP1oXyAlq) button brings you 10 records forwards. * The ![Image](/files/-LNl8WjrX3z4Gsc0lDU-) button brings you to the last record. * The ![Image](/files/-LNl8WjteOMEnhm4QOio) button enters the edit mode. * The ![Image](/files/-LNl8WjvdUlaIfQjbvSj) button leaves the edit mode and accepts the changes. * The ![Image](/files/-LNl8WjxtMeI9wW010AS) button leaves the edit mode and rejects the changes. Even though you can accept changes in the edit mode, ultimately they will only be saved by leaving the dialog and pressing the **OK** button. Changes done within the dialog are highlighted with orange background color. ![Highlighting of Changes](/files/-LNl8WjzBHLYJcMFXBgN) If you want to discard all changes you can just leave the dialog with the **Cancel** button. # Creating Individuals In the building block **Individual** the properties of individuals are defined. In the database underlying PK-Sim®, anatomical and physiological information on various animal species, as well as humans of different populations, genders, and ages, is provided. The algorithm for creating virtual individuals differs for animals and humans: * In the case of **animal species**, no age-dependent distribution information for the anatomical and physiological parameters is included in the database so far. The generation of an animal with a predefined body weight is thus done by linear scaling of an average animal of the given species. Consequently, all organs always contribute to the same relative extent to the total body weight, and differences, e.g., related to growth or to different races of the respective animal species are not taken into account. * For **humans**, the population parameters database that comes with PK-Sim® includes information on the dependence of anatomical and physiological parameters relevant for PK-Sim® such as organ weights, blood flow rates, or tissue composition on age, gender, body weight, body mass index, which have been collected in a comprehensive literature search. Thus, when creating an individual of a given **Age**, **Weight**, and **Height**, the parameters will be adjusted based on the information included in the underlying database. There are three classes of parameters that are adjusted: * Organ volumes * Further parameters for which distribution data are available in the database, e.g. the hematocrit value. * The volume fractions, which are scaled using a global scale factor taken from the database {% hint style="info" %} Please note that the volume of fat tissue is not optimized by the algorithm as this value is used to match the target body weight. {% endhint %} ## Definition of new Individual in PK-Sim® * Click on **Individual** in the **Create** Group of the **Modeling** Tab or * Right mouse click on **Individuals** in the **Building Block Explorer** and select **Add Individual...** or * Use the shortcut **Ctrl+Alt+I** A dialog will pop up in which the properties of the individual can be specified. First, new individuals are initialized by giving them a **Name** in the respective input field. These names are then used to identify them when their properties are saved in the project and/or as templates. In addition, names are used for identification of individuals in the simulation. Second, the properties of individuals can be set or changed: ![The Create Individual dialog. Here, the properties of a standard European individual are shown.](/files/4oFopIgnKpfplAdA3fiT) The **Create Individual** window is subdivided into three tabs: **Biometrics, Anatomy & Physiology**, and **Expression**. ### Biometrics In the first drop-down menu you can choose from the following species: * Human * Monkey * Beagle * Dog * Minipig * Rat * Mouse * Rabbit * Cat * Cattle ### Human If **Human** is selected, you can select one of the following populations from the next drop-down menu: * East Asian (Tanaka, 1996) \[[74](/references/references#74)] * Black American (NHANES, 1997) \[[82](/references/references#82)] * European (ICRP, 2002) \[[84](/references/references#84)], \[[113](/references/references#113)] * Mexican American -White (NHANES, 1997) \[[82](/references/references#82)] * White American (NHANES, 1997) \[[82](/references/references#82)] * Japanese \[[67](/references/references#67)] * Preterm \[[111](/references/references#111)] * Pregnant (Dallmann et al. 2017) \[[107 - 110](/references/references#107)] In the following drop-down menu, the gender is specified. Further below, the **Individual Parameters** can be defined. In the case of the human Asian, Black American, European, Mexican American, and White American populations, the individual is characterized by the following parameters: * Age: The age in units of year(s), month(s), week(s), or day(s). * Weight: The body weight in units of kg or g. * Height: The body height in units of cm or m. By clicking on the **Mean** button, the average body weight and height of the individuals of the given population as well as gender and age will be generated based on the database information. If as a special human population **Preterm** is selected, an additional age scale has to be taken into account. Preterm neonates are characterized by their gestational age (GA), which ranges between about 24 and 37 weeks, and their postnatal age (PNA). In the model, preterm neonates catch up growth during their first two years of life so that there are no differences in a >2 years old individual of the same race and gender born preterm or born term. ![Postnatal growth curves for preterm infants pooled into different weight classes up to two years (black solid lines) compared to term born infants matched to the growth charts of the “Centers for Disease Control and Prevention” (CDC, shaded area).](/files/-LNl8XL8uM6YoF44evyu) {% hint style="warning" %} Oral administration to preterm neonates is, so far, not possible in PK- Sim®. The parameters relevant to oral administration are all set to "0" so that the fraction of dose absorbed and, in addition, the distribution of drugs into the mucosa irrespective of the administration route are disabled. {% endhint %} {% hint style="info" %} Please note that gender-specific information for all parameters except body weight and height (biometrics) was not available for preterms.Therefore, it is an assumption that for a given body weight the organ weights and blood flow rates are equal for males and females. {% endhint %} #### Disease State Depending on the selected population, a disease state for the selected individual can be specified. By default, the individual will be created as **Healthy**. #### Healthy Healthy individuals in PK-Sim are representative of the general population of individuals in the specified ethnicity and/or geographic area. These individuals are parameterized under the assumption that they have no chronic or comorbid disease states that would have a relevant effect on anatomy, physiology or drug disposition. #### Chronic Kidney Disease (CKD) Chronic kidney disease is renal impairment lasting at least 3 months. The disease is staged according to eGFR. Over time, multiple other body systems are also affected. To apply this disease state to an individual in PK-Sim, first select the targeted eGFR. Accordingly, the individual will display changes in GFR, kidney volume, kidney blood flow, plasma protein binding, hematocrit, gastric emptying time, and small intestinal transit time. This parameterization is for individuals with CKD who are not on dialysis. It does not modify the expression or activity of enzymes or transporters - only foundational anatomy and physiology. Users should consult scientific literature for information how the relevant enzymes and transporters for their purposes may be affected. For more information on the implementation, please refer to \[[122](/references/references#122)] ### Animal species If one of the animal species, i.e. **Monkey, Beagle, Dog, Minipig, Rat** or **Mouse** is selected, the menu items are slightly different. {% hint style="info" %} Please note that PK-Sim® does currently not distinguish between male and female animals. Animal models represent an average adult animal of the species or breed. {% endhint %} If desired, the body weight of an animal can be changed under **Individual Parameters**. By changing the body weight of the animal, PK-Sim® automatically scales the weight of the different organs ( see [**Anatomy & Physiology**](#anatomy--physiology) tab) by keeping their relative contribution to the total body weight constant. Likewise, the organ blood flow rate will be re-calculated by keeping the organ specific blood flow rate, i.e. the blood flow rate per kg of tissue weight. {% hint style="info" %} Significant breed-specific differences exist for some animal species. For example, a Beagle dog obviously has a different physique than a Labrador and the body weight of an adult Yucatan minipig doubles that of a Göttinger minipig. See below for tips to determine how each species is defined in PK-Sim®. {% endhint %} * For monkeys, the default values represent an average monkey with a body weight of 5.6 kg. The monkey-specific physiological parameters were derived for macaques such as rhesus and cynomolgus monkeys \[[98](/references/references#98)]. * The default dog-specific physiological parameters were obtained from literature and represent an average dog with a weight of 13.7 kg. Breed specific differences are not taken into account. Still, for the most popular breed of dogs, the beagle, anatomical and physiological information specifically representing an adult beagle dog that weights 10.5 kg is implemented \[[1](/references/references#1)]. * For minipigs, the default body weight is 40 kg. An important feature of the minipig is the reported delay in gastric emptying. Furthermore, emptying appears to be incomplete, so there may be food present in the stomach for 24 hours a day. The high variability in gastric pH and emptying should be taken into account, particularly when monolithic controlled release and enteric-coated dosage forms are intended to be simulated. * For the rat-specific physiological parameters affecting oral absorption from the GI tract see \[[93](/references/references#93)]. An important feature of this species is that the rat lacks a gallbladder. As a result, bile fluid is secreted continuously in dilute form, which has an important effect on biliary clearance and entero-hepatic circulation (see [PK-Sim® - Events](/working-with-pk-sim/pk-sim-documentation/pk-sim-events)). * If mouse is selected, the anatomical and physiological data are set at default values for a mouse with a mean weight of 20 g. * For rabbits, the default body weight is 2.5 kg. For the parameter values not found in the literature, the mouse PBPK model parameters were transferred and used, as it is the closest animal species to the rabbit among the species available in the physiology database (e.g., mouse retains a gallbladder unlike the rat). \[[112](/references/references#112)] * Currently, only for mouse, monkey and human species specific values for the concentration of the FcRn receptor, the concentration of the endogenous IgG and the affinity of the endogenous IgG to the FcRn receptor (needed for the **Model for proteins and large molecules**) are available. For all other animal species, the concentrations are taken from the human model and the Kd(FcRn) of the endogenous IgG in endosomal space is set to 0.75 µM. Irrespective of the species chosen, the **Calculation Method** for the estimation of the surface area of the capillary endothelium has to be selected. The endothelial surface area is needed for calculation of the rate of permeation through the endothelial barrier between plasma and interstitial space, which is determined by the permeability - surface area product. The drug dependent specific organ permeability can be defined in the **Compound** building block (see [PK-Sim® - Compounds: Definition and Work Flows](/working-with-pk-sim/pk-sim-documentation/pk-sim-compounds-definition-and-work-flow)). Literature for capillary surface areas for the different organs and species is rather limited. Therefore, PK-Sim® provides two heuristics to estimate the capillary surface area of the organs, which can be selected from the drop-down menu 1. **Organ vascularization (default method)**. The capillary surface area (SA) is estimated by ![Image](/files/-LNl8XLDREDzWvaHasE2) , with the constant of proportionality k, the fraction of vascular space of an organ ![Image](/files/-LNl8XLGLcQP7j7T0wT0), and the organ volume ![Image](/files/-LNl8XLJ0xCT1RdUk-DI). The idea behind this heuristics is the following: with the assumption that the morphology of the vascular tree is similar in each organ, the specific surface area per organ volume can be estimated by the capillary density of an organ, which in turn can be estimated by the fraction of vascular space of an organ. 2. **Blood flow.** The capillary surface area is estimated by ![Image](/files/-LNl8XLQNT5I5vwROtCP)\ , with the constant of proportionality $$k$$, the organ blood flow $$Q\_{organ}$$, the shape factor $$beta$$ (default: $$beta=1$$). The permeability-surface area product ![Image](/files/-LNl8XLVAm5v_p-CFTpp) is related to the extraction $$E$$ by ![Image](/files/-LNl8XLYlIctNt6I5QeY) \[[8](/references/references#8)]. With the assumption that the extraction of drug in each organ is equal, ![Image](/files/-LNl8XLc1MlBxwG9IBOQ) is obtained. If it is further assumed, that the permeability is equal for each organ one obtains ![Image](/files/-LNl8XLeINnmASSA0eIB). ### Anatomy & Physiology Anatomical and physiological properties in PK-Sim® are set at default values for a mean representative of a species. These default values were carefully selected from literature. In the human species module, also the mean values for children of all age groups are included. For some purposes, e.g. to simulate pathological disorders, it is desirable to change these values. This can be done in the **Anatomy & Physiology** tab, in which the parameters are, using the default settings, displayed in a tree structure on the left hand side. By default, a **Simple** view of the various properties is displayed, in which only the most relevant parameters are shown. Using the drop-down menu at the bottom of the window, you can switch to the **Advanced** tree view or to the **Hierarchy** view. In the **Simple** and the **Advanced** view, the parameters are grouped based on function whereas in the **Hierarchy** view, they are listed according to the internal model structure. Please note that only containers comprising visible parameters are displayed. There are additional parameters in the model which are not displayed in PK-Sim®. They are, however, displayed in MoBi®. For details please see [Working with MoBi®](/working-with-mobi/mobi-documentation/first-steps). The tree view shows only drawings that are currently open. To access the various parameters, 1. Click on the light grey arrow to open the respective tree view node 2. If present, click on the next light grey arrow to open the subsequent level of the tree view 3. Click on the desired parameter group {% hint style="info" %} Use the **Filter** function above the tree view to find parameters more quickly. {% endhint %} In the window on the right hand side, the details of the respective parameter group will be shown. Typically, the first column(s) contains the **Name** of the parameter and/or its location (i.e. the organ or segment). In the next column, the default **Value** for the parameter in the given organ or segment for the species selected is provided together with the corresponding unit. For humans, the column **Percentile** depicts the percentile within the respective population. If an average subject is selected, this bar should be equal or at least close to 50%. In the last column, you can define parameters as **Favorites** in order to select certain parameters, e.g. if they have to be changed frequently. Parameters defined as favorites will be listed in the undermost node of the tree view and are thereby easily accessible. {% hint style="info" %} The order of the columns can be changed manually. Drag the column header to the desired position to change the sequence of columns. {% endhint %} {% hint style="info" %} The column by which the parameters are grouped can be selected. Drag the column header to the top of the table into the group box. {% endhint %} To change the value of a parameter, do one of the following * Enter a new value in the respective input field * Multiply the default values with the scale option There are three types of parameter values: 1. Parameter values displayed by default on a white background represent constants values. By changing the parameter value, the default value will be overwritten and the background of the field turns yellow. To reset the parameter value to default click **Reset parameter to default** or use the **Rollback** function of the **History manager**, see [Shared Tools - History manager and history *reporting*](/shared-tools-and-example-workflows/history-manager-history-reporting). 2. Parameter values displayed by default on a light blue background represent parameters calculated using a formula. By changing these values, the formula is overwritten and the background of the field turns yellow. To reset to the default value(s) click **Reset parameter to default** . 3. Parameter values displayed by default on a grey background represent values which cannot be changed by the user, because otherwise a fundamental relationship could be destroyed. {% hint style="info" %} The background colors that indicate the different types of parameters (1.-3.) can be changed by the user. For details please see [PK-Sim® - Options](/working-with-pk-sim/pk-sim-documentation/pk-sim-options). {% endhint %} For some parameters, reasonable ranges are defined. For example pH values should be less than or equal to 14. In case a value outside this range is defined, a warning appears and the window cannot be closed without setting the parameters to a reasonable value. #### Liver Zonation The **Advanced** view offers the implementation of a zonated liver into an individual. Metabolic pathways in the liver are spatially separated along the liver sinusoids \[[29](/references/references#29)]. Splitting the liver into more than one zone will improve simulation accuracy. As shown below, the liver is not zonated per default (only periportal zone). Upon zonation, the liver is split into a periportal and a pericentral zone. The parameter **Fraction of periportal zone** defines the ratio of the zone volumes and the surface areas and is set to 50% per default. ![The Advanced view in the Anatomy/Physiology tab offers the use of a zonated liver.](/files/-LNl8XLvZc2htcyGi3FX) Switching between zonated and non-zonated liver does not alter the model structurally, but changes only the model parameterization. The relative expressions for enzymes, transporters and binding proteins can be set independently for both zones. The relative expression in the pericentral zone have no effect if the liver is not zonated. Currently, the PK-Sim gene expression database delivers the same relative expression for both zones for all proteins, but this will be improved in the future. {% hint style="warning" %} Please note that when switching to another species on the Biometrics tab all parameters of the individual defined in the **Anatomy & Physiology** tab and in the **Expression** tabs, including applied changes (e.g. active processes), are overwritten. {% endhint %} {% hint style="info" %} **User Defined** parameter node shows an overview of all parameters changed by the user in the individual. {% endhint %} ### Expression In the **Expression** tab, all relevant enzymes, transport proteins and protein binding partners can be defined for the selected individual. For details on how to create an expression profile, please see [PK-Sim® - Expression Profile](/working-with-pk-sim/pk-sim-documentation/pk-sim-expression-profile). To add a protein to the individual, right click on the corresponding protein type in the tree view and select the corresponding action in the context menu ![Add a metabolizing enzyme](/files/fvq7BiN8rtqc8c1BJ55G) This will open a view to select the expression profile to link with the individual. Either select an existing expression profile, load one from template or create a new one by clicking on ![Select an expression profile](/files/PZknITaSsx2cPh9XUih8) Once the expression profile is selected, it will be linked to the individual and displayed in the **Expression** tab. ![Expression profile linked to individual](/files/og3tgDMFArEK7vjTnV6T) This is the only instance in PK-Sim where a a building block is referencing another building block. {% hint style="warning" %} Please note that when adding an expression profile to an individual, the expression profile is linked directly to the individual. Any modification performed in the expression profile will be immediately reflected into the individual. This is the reason why all parameters are read-only in the individual. {% endhint %} ### Editing and Scaling Individual Properties To edit properties of existing individuals: 1. Right mouse click on the respective individual in the **Building Block Explorer** 2. Select **Edit...** or simply double click on the existing individual in the **Building Block Explorer**. This will open the properties window of the individual. The properties defined in the **Anatomy & Physiology** tab and those defined in the **Expression** tab can be set or changed appropriately. Changes are saved by simply closing the window (click on ![Image](/files/-LNl8Q5_I6QLMwPlc1Ju) ). Please note that the **Biometrics** of an existing individual cannot be changed later on. In order to change the **Biometrics** please create a new individual or use the scale function. Using the scale function transfers modifications at the individual and expression levels to the scaled individual. In order to **scale** an existing individual: 1. Right mouse click on the respective individual in the **Building Block Explorer** 2. Select **Scale...** The **Scale Individual** dialog opens, which is divided into four tabs: **Biometrics**, **Scaling configuration**, **Anatomy & Physiology**, and **Expression**. Details about the three tabs **Biometrics**, **Anatomy & Physiology**, and **Expression** have already been described for the **Create Individual** dialog (please see above). Here, only details about the tab **Scaling configuration** are given: If, and only if, certain individual parameters such as organ weights or blood flow rates were modified in the base individual used for scaling, these parameters will be listed in this tab. This is e.g. the case if an individual with specific characteristics due to certain diseases (e.g. renal or hepatic impairment) was created and you would now like to transfer these changes to another individual. The following six columns appear in the **Scaling configuration** tab: * **Parameter**: The name of the parameter modified in the base individual used for scaling. * **Source default value**: The original value of the parameter in the base individual according to the database underlying PK-Sim®. The source default value depends on the biometrics (race, age, and gender) of the base individual. * **Source value**: The modified value of the parameter in the base individual. * **Default value**: The default value of the parameter in the scaled individual according to the database underlying PK-Sim®. This value will differ from the source default value if the scaled individual is characterized by different biometrics (race, age, and/or gender). * **Scaled value**: The modified value of the parameter in the scaled individual. This value depends on the scaling method selected in the last column (Scaling method): * **Scaling method**: Select between four options for the scaling method from the drop-down menu: 1. **Same percentile**: This method is only available in the case of distributed parameters such as organ weights and blood flow rates in human populations. If a modification was made in the base individual the parameter value will not represent an average value anymore, i.e. it will not lie on the 50th percentile of the distributed parameters for the given population (characterized by race, age, and gender). Choosing this option, the same percentile will be used for your scaled individual of the selected population based on the PK-Sim® database. 2. **Use default value**: The modification made in the base individual will not be transferred to the scaled individual. Instead, the default value of the parameter in the scaled individual according to the database underlying PK- Sim® will be used. 3. **Use source value**: If a modification was made in the base individual the identical parameter value will be used in the scaled individual. Please note that for most parameters this is only a reasonable option if the biometrics (race, age, gender) of the base and the scaled individual are identical or at least similar. 4. **Same ratio**: The ratio of the source value divided by the source default value is multiplied by the default value of the scaled individual. The line **Target weight**, which appears only on the top of this window if modifications in organ volumes were made in the base individual, indicates the body weight of the scaled individual. A modification of organ volumes will automatically lead to a change in total body weight, which is the sum of all organ weights. Thus, if the default value of an organ weight is changed, the new body weight, which is no longer in agreement with the body weight previously selected on the biometrics tab, will be shown. ### Clone an Individual To clone an individual in the project: 1. Right mouse click on the respective individual in the **Building Block Explorer** 2. Select **Clone...** 3. Set an alternative name for the clone and enter a description if desired 4. Confirm and close the window by clicking **OK** ### Saving of Individuals as Templates Previously defined individuals can be saved as a template in the template database and then be shared among several projects and users. To save an existing individual as template: 1. Right mouse click on the respective individual in the **Building Block Explorer** 2. Select **Save as Template...** A message will appear confirming that the Individual was successfully saved in the template database. In case an individual with the same name already exists, a warning message will pop up and you have the following opportunities: * Override: This action will override the existing template. * Save as: You can save the individual under a different name. In this case, you will be asked to Rename the new template. * Cancel: This action will abort the saving process. ### Loading existing Individuals from Templates To load existing individuals from the template database: 1. Right mouse click on **Individuals** in the **Building Block Explorer** 2. Select **Load From Template...** 3. Select the desired individual from the user templates. In case an individual with the same name already exists in the project, a warning appears and you will have to **Rename** the individual that is to be loaded from template. 4. Click **OK** The selected individual will appear in the **Building Block Explorer** view. In addition, individuals can be directly loaded from the template database within a simulation (see [PK-Sim® - Simulations](/working-with-pk-sim/pk-sim-documentation/pk-sim-simulations). ### Deleting Individuals To delete individuals from a project: 1. Right mouse click on the respective individual in the **Building Block Explorer** 2. Select **Delete...** 3. Confirm to delete the individual by clicking **Yes** {% hint style="warning" %} Please note that an individual that is used in any simulation of the project cannot be deleted. {% endhint %} # Creating Populations The properties of a population of individuals can be defined in the building block **Population** using the physiological database of PK-Sim®. * In case of the various **animal species**, no age-dependent distribution information for the anatomical and physiological parameters is included in the database so far. The algorithm generates random values in the \[Minimum Weight, Maximum Weight] interval defined by the user. The generation of a population is done by linear scaling of an average animal of the given species. This means that all organs always contribute to the same extent to the total body weight without taking into account differences related to, e.g., growth, or to different races of the respective animal species. * For **humans**, the population parameters database that comes with PK-Sim® includes information on the dependence of anatomical and physiological parameters relevant for PK-Sim® such as organ weights, blood flow rates, or tissue composition on age, gender, body weight, and body mass index, which have been collected in a comprehensive literature search. The algorithm generating a population then involves the following steps which are repeated until the target number of individuals is reached \[[97](/references/references#97)]: A list of individuals is created with the proportion of males and females as defined by the user. For each individual, the algorithm tries to create a parameter set that fulfills the defined criteria (for more detailed description of the algorithm, see [Create Individual Algorithm](https://github.com/Open-Systems-Pharmacology/OSPSuite.Documentation/wiki/Create-Individual-Algorithm)): 1. An **Age** value is drawn from a uniform random number distribution in the **\[Minimum Age, Maximum Age]** interval. 2. For the **Age** assigned above, a **Height** value is randomly generated according to the height distribution defined in the database for the given **Age**. 3. The generation of the **Height** value might fail (i.e., the generated **Height** is not within the **\[Minimum Height, Maximum Height]** interval for **Age** drawn in 1.). In that case, the algorithm tries to perform steps 1. and 2. again. After a maximum of 100 attempts, it is assumed that no data is available in the database matching the user inputs, and an exception is thrown. 4. With **Age** and **Height** defined, the algorithm tries to create a random individual based on these values. The resulting body **Weight** should be in the **\[Minimum Weight, Maximum Weight]** interval. The organ volumes are randomly generated according to their organ volume distributions. If the resulting body weight, i.e., the sum of all organ volumes times their density, is in the specified **\[Minimum Weight, Maximum Weight]** interval, the individual is kept. If not, another individual is generated. This step is repeated up to 100 times. If then still no individual with a body weight within the **\[Minimum Weight, Maximum Weight]** interval is found, an exception is thrown. 5. The volume fractions of protein, water, and lipids of different organs are scaled according to the value defined in the database for the given age. 6. Finally, all parameters other than organ volumes for which distributions are available in the database (e.g., blood flow rates, hematocrit, etc.) are being randomly generated according to their distributions. 7. Finally, the algorithm checks that the **BMI** value corresponding to the generated **Height** - **Weight** combination is within the **\[Minimum BMI, Maximum BMI]** interval, which is either defined by the user, or queried from the database for the generated combination of age and weight. If so, the individual is added to the population. If not, the individual is discarded. The following figures show, as an example, the age dependency of the body weight, body height, and body mass index distributions for a certain population (white males). The data were taken from the NHANES study \[[82](/references/references#82)]. ![Age dependence of the distribution in body weight for white males according to the NHANES study](/files/-LNl8Q5IuZZzXdNZa3ZW) ![Age dependence of the distribution in body height for white males according to the NHANES study](/files/-LNl8Q5KKW1P2dH748Tf) ![Age dependence of the distribution in body mass index for white males according to the NHANES study](/files/-LNl8Q5MfgmAVlqmlPWQ) ## Definition of new Populations in PK- Sim® To create a new population, do one of the following: * Click on **Population** in the **Create** Group of the **Modeling & Simulation** Tab, or * Right mouse click on **Populations** in the **Building Block Explorer** and select "Add Population...", or * Use the shortcut **Ctrl+Alt+P** A dialog box will open where the properties of the population can be selected and/or defined. The **Create Population** dialog is subdivided into four tabs: **Demographics**, **Expression**, **User Defined Variability**, and **Distribution**. The population is initialized by giving it a **Name** in the respective input field. The name is used to identify the population when its properties are saved in the project and/or as a template. Moreover, the name is used for identification of the population in the simulation. ### Demographics tab In the first drop-down menu (**Based on individual**) you can specify an **Individual** that you previously defined in this project, specify the number of individuals in your population, and the percentage of females therein (only for humans). Further below, the **Population Parameters Ranges** can be set, i.e., the anthropometry of the individuals can be constrained, at the lower and/or upper ends of the ranges for the different properties. {% hint style="info" %} Please note that for animal populations the minimum and maximum body weight represent required input parameters. {% endhint %} {% hint style="warning" %} Technically, there is no restriction on the \[Minimum Weight, Maximum Weight] interval values. However, please note that the generation of an animal population simply results from linear scaling of the average animal species with the algorithm generating random values in the entire \[Minimum Weight, Maximum Weight] interval defined by the user. Hence, reasonable values should be chosen for this interval. {% endhint %} If no individual has been defined, you can: * Create a population based on an individual saved as a template: * Click on **Load** in the **Demographics** tab next to the **Based on individual** drop-down menu. * Select the individual from **User Templates** or the **Predefined Templates** * Click OK * If the name of the **Individual** loaded from template is already used in the project, a new name has to be defined. * Create a new individual which serves as a basis individual for the population: * Click on **Create** * Define the properties of the **Individual**. For details see [PK-Sim® - Creating Individuals](/working-with-pk-sim/pk-sim-documentation/pk-sim-creating-individuals). If a human population is selected, the following parameters can be defined in the **Population Parameters Ranges** section: * Age: The age range in units of year(s), month(s), week(s), or day(s). The population database contains physiological information starting from preterm newborns to newborns (age "0") to 80 year old (100 years old for the European (ICRP, 2002) population) individuals. When a pediatric or an elderly population is simulated, only the age dependence of anatomical properties (size of the organs, blood flow rates, body composition, etc.) is considered. However, important pharmacokinetic differences in children and elderly can be caused by age-related differences in, for example, hepatic metabolic activity. These effects are automatically accounted for if the ontogeny of the elimination process has been defined in the **Expression** tab for the underlying **Individual**. To manually account for variations in elimination, use the **User Defined Variability** tab. * Height: The range of body heights of the individuals in units of cm or m. * Weight: The range of body weight of the individuals in units of kg or g. * BMI: The range of body mass index of the individuals in units of kg/m2. The BMI is a measure for the human fat content. It is given by the individual's height (H) and body weight (BW) according to the equation $$BMI = \frac{BW}{H^2}$$. If the population **Preterm** is selected, an additional age scale has to be taken into account. Preterm neonates are characterized by their gestational age (GA), which ranges between about 24 and 37 weeks, and their postnatal age (PNA, what we usually refer to as "Age"). In the model, preterm neonates catch up growth during their first two years of life so that there are no differences between a > 2 year old individual of the same race and gender born either preterm or term. {% hint style="info" %} Please note that for human populations, the minimum and maximum age (and gestational age in case of preterms) are required input parameters. For height, weight, and BMI, empty fields indicate the unconstrained state. The population database contains information on the age dependence of the body weight, body height, and BMI distributions of various human populations. {% endhint %} {% hint style="warning" %} The algorithm will only create virtual individuals with reasonable characteristics, i.e., that are in agreement with the database. It is, for example, impossible to create a 30 year old male with a height of 100 cm weighing 200 kg. If implausible combinations of weight, height, and BMI are given as constraints, PK-Sim® will not be able to create any individuals. {% endhint %} ### Expression tab In the tab **Expression**, proteins that should be expressed in the population can be defined. See section [PK-Sim® - Expression](/working-with-pk-sim/pk-sim-documentation/pk-sim-expression-profile) for details on how to define the expression of proteins in an individual. ### User Defined Variability tab In the **User Defined Variability** tab, further physiological parameters can be varied, e.g., the gastrointestinal transit pattern, or transport or elimination via active processes. The parameters that are available for additional statistical variation are grouped based on their function and displayed, using the default settings, in a tree structure on the left hand side. Two parameter groups will always be available, namely the **Anatomy** and the **Physiology** parameter groups. The appearance of a third parameter group, the **Relative expressions**, is dependent on the processes defined in the underlying individual. To select a parameter in the tree view, do the following: 1. Click the plus sign (+) to open the respective tree view node 2. If present, click the next plus sign (+) to open the subsequent level of the tree view 3. Click on the desired parameter {% hint style="info" %} Use the **Filter** function above the tree view to find parameters more quickly. {% endhint %} Selected parameters can be added to the box on the right hand side by clicking **Add**. Accordingly, parameters can be removed from the box by clicking **Remove**. Parameters added to the box on the right hand side can be varied within the population simulation. For each parameter, a type of distribution and associated properties of the distribution can be chosen. Four types of distributions are available: * **Normal:** The parameter is normally (Gaussian-like) distributed. Mean and standard deviation must be given. Select the unit accordingly. * **LogNormal:** The parameter is log-normally distributed. Mean and geometric standard deviation must be given. Select the unit for the mean value accordingly. The standard deviation can be given as a (dimensionless) relative standard deviation. * **Uniform:** The parameter is evenly distributed between the minimum and maximum value. Select the unit accordingly. * **Constant:** The mean value is used for all individuals. Select the unit accordingly. {% hint style="info" %} Variability in clearance processes does not only originate from variability in the organ volume or blood flow to the eliminating organ, but also from variability in the expression levels of the protein involved. Therefore, variations of the reference concentration of the enzyme or transporter can be taken into account in addition to the variability that automatically results from the physiological variations. {% endhint %} {% hint style="info" %} In case of a virtual human population that contains individuals of different ages, PK-Sim® automatically takes into account the developmental changes in the specific glomerular filtration rate, i.e. in the glomerular filtration rate normalized to the volume of the kidney. However, like for active processes, additional variations of the specific glomerular filtration rate can be taken into account. {% endhint %} {% hint style="info" %} If for active processes, i.e., metabolizing enzymes, transport proteins, and protein binding partners, an ontogeny function was selected in the **Expression** tab of the **Individual** building block for the basis individual, relative activity as a function of age will be taken into account in the human population. {% endhint %} ### Distribution tab In the **Distribution** tab, the distribution of parameters that are variable in the virtual population are shown. To select a certain parameter, mark it in the parameter tree on the left hand side. Again, you can use the **Filter** function above the tree view to find parameters more quickly. The distribution of the parameter selected will be depicted in the adjacent graphic. The parameter distribution can either be displayed as absolute counts or as percentage. Choose either **Count** or **Percent** from the drop-down menu below the parameter tree. For human populations, the parameter distributions are color coded. In case of a virtual human population that contains male and female individuals, you can select from the first drop-down menu whether all, only male, or only female individuals should be displayed. If **All** is selected, the gender specific data can either be shown as neighboring bars or stacking bars. {% hint style="info" %} The distribution of any parameter can be copied as image via right mouse click on the graphic on the right hand side of the tab. {% endhint %} ## Setting or Editing Population Properties To set or edit the properties of an existing population: 1. Right mouse click on the respective population in the **Building Block Explorer** 2. Select **Edit...** or simply double click on the existing population in the **Building Block Explorer**. The window with the properties of the population will open. The properties defined in the **Additional Parameters** tab can be set or changed appropriately. Changes can be verified in the **Distribution** tab. After having set or changed the properties, the window can be closed by clicking on ![Image](/files/-LNl8Q5_I6QLMwPlc1Ju) which will save the changed population properties. {% hint style="info" %} Please note that the **Demographics** of an existing population, including all parameters automatically generated by the population algorithm, cannot be changed later on. In order to change the **Demographics**, please create a new population. {% endhint %} ## Exporting Populations to CSV Populations generated in PK-Sim® can be exported to a CSV format. The file, which can be opened in Excel®, contains all anatomical and physiological parameter values of each individual of the population. In order to export a population to csv: 1. Right mouse click on the respective population in the **Building Block Explorer** 2. Select **Export to CSV...** 3. Choose directory and enter file name 4. Click **Save**. The file is saved and can be subsequently opened with excel {% hint style="info" %} In addition to the export of the population parameters to CSV, population simulations can be exported to CSV via the Simulation Explorer. Then, the population parameters file (.CSV), the respective model file (.pkml), and an information file (.txt) with the relevant information about the PK-Sim® version number will be generated. For details please see (see [PK-Sim® - Importing and Exporting Project Data and Models](/working-with-pk-sim/pk-sim-documentation/importing-exporting-project-data-models). {% endhint %} ## Extracting individuals You can extract specific individuals from a population and add them as standalone building blocks to the project for follow-up analyses. Individuals of interest can be identified within a population analysis (e.g. individuals associated with the percentiles displayed in a population Box-Whisker plot) To extract individuals from a population, right click on the respective population in the **Buildings Block Explorer** and select **Extract Individuals...**. ![Dialog for extracting individuals from a populatoin](/files/4WI2JVHwxZOsuBnW8WBK) ## Cloning of Populations To clone populations in the project: 1. Right mouse click on the respective population in the **Building Block Explorer** 2. Select **Clone...** 3. Set an alternative name for the population clone and enter a description, if desired 4. Confirm and close the window with **OK** ## Saving Populations as Templates Previously defined populations can be saved as templates and then be shared among several projects and users. To save an existing population as template: 1. Right mouse click on the respective population in the **Building Block Explorer** 2. Select **Save as Template...** In case a population with the same name already exists, a warning message will pop up and you have the following options: * Override: This action will override the existing template * Save as: You can save the population under a different name. In this case, you will be asked to Rename the new template. * Cancel: This action will abort the saving process ## Loading of existing Populations from Templates To load an existing population from the template database: 1. Right mouse click on **Populations** in the **Building Block Explorer** 2. Select **Load From Template...** 3. Select the desired population from the user templates In case a population with the same name already exists in the project, a warning message will pop up and you will have to **Rename** the population that is to be loaded from the template. 4. Click **OK** The selected population will appear in the **Building Block Explorer** view. In addition, populations can be directly loaded from the template database within a simulation (see [PK-Sim® - Simulations](/working-with-pk-sim/pk-sim-documentation/pk-sim-simulations). ## Deleting Populations To delete a population from the project: 1. Right mouse click on the respective population in the **Building Block Explorer** 2. Select **Delete...** 3. Confirm to delete the population by clicking on **Yes** {% hint style="warning" %} Please note that a population that is used in any simulation of the project cannot be deleted. {% endhint %} # Compounds: Definition and Work Flows A **Compound** is a set of data that describes the properties of the substance whose behavior is to be simulated. These properties are defined within the building block **Compound**. For each project, several compounds may be defined. The compounds defined can be saved as templates and shared among several projects and users. ## Definition of new Compounds in PK- Sim® To create a new compound, do one of the following: * Click on **Compound** in the **Create** Group of the **Modeling** Tab, or * Right mouse click on **Compounds** in the **Building Block Explorer** and select **Add Compound...**, or * Use the short cut **Ctrl+Alt+C**. A dialog will open, where the properties of the compound can be defined. The compound is initialized by giving it a **Name** in the respective input field. The properties of the compound can then be set or changed: ![The Create Compound dialog. Here, the basic physico-chemical properties of diclofenac are shown.](/files/-LNl8Z4Q9tVgLydNHgT-) The **Create Compound** window is subdivided into three tabs: **Basic Physico-chemistry**, **ADME Properties**, and **Advanced Properties**. ### Basic Physico-Chemistry tab The basic physico-chemical properties of a compound are specified in the **Basic Physico-chemistry** tab. Most of the drug properties can have multiple values, e.g., coming from differed sources, determined using various methods or assays. During the simulation creation, you can choose one value for each property. #### To Enter an additional value: 1. Click **Add** at the end of a row. 2. Enter the alternative name 3. If desired, enter a short description in the respective input field 4. Click **OK** #### To delete a value: 1. Click **Delete** 2. Click **Yes** If several alternative values have been defined, you can select a default one by enabling the check box "Default". When setting up the simulation, a value set as default will be selected first. The alternative values can still be selected, if desired. {% hint style="info" %} Please note that a value set as default cannot be deleted. In order to delete the value, define another default value. {% endhint %} #### **Is small molecule** This checkbox defines whether the compound is a small molecule or a large molecule such as a protein. If not selected (i.e., the compound is treated as a large molecule), the permeability for passive diffusion into blood cells and into the intracellular space of the organs as well as the intestinal permeability are set to zero, as it is assumed that large molecules do not passively diffuse across the cell membranes. If the drug is a small molecule and is used in a **Model for proteins and large molecules**, the drug will not enter the endosomal space (see [Modeling of Proteins](/mechanistic-modeling-of-pharmacokinetics-and-dynamics/modeling-concepts/modeling-concepts-modeling-of-proteins)). #### **Lipophilicity** {% hint style="info" %} Lipids in organ tissue are predominantly present in the form of phospholipid membranes. The best descriptor for lipophilicity is the partition coefficient between lipid membranes and water, as determined at physiological pH \[[43](/references/references#43)]. This is called membrane affinity and the value to be entered is the logMA. It is recommended to use these membrane affinities as input parameters for PK-Sim®. With their use, it is very likely that specific organ and intestinal permeability coefficients are obtained that require no or only marginal adjustment. {% endhint %} {% hint style="info" %} If the membrane affinity is not available, other lipophilicity values (e.g., logP, clogP) can be used as surrogates. In this case the quality of the simulation results might be negatively affected. The membrane/water partition coefficient is predominantly affected by two contributions. A real lipophilicity, which describes the partitioning into the lipid core of a membrane, and the interaction between a molecule and the phospholipid head groups. Particularly for charged substances this can lead to large differences between membrane affinity and other lipophilicity descriptors. A common observation is that membrane affinity is much less pH dependent than, e.g., logD \[[21](/references/references#21)]. For this reason, it is recommended to use a lipophilicity value for the neutral form, e.g., logP, as a replacement for membrane affinity if the latter is not available. A reasonable variation around the logP value should be allowed since this parameter is not 1:1 correlated with the membrane affinity. {% endhint %} #### **Fraction Unbound (plasma, reference value)** The free fraction of drug in plasma (fu) is a mixed parameter depending on both the species and the drug. Thus, it might be necessary to define several values for one compound, namely one for each species to be simulated. The respective species can be selected in the **Species** column from the drop-down menu. Later, during the create simulation process, the appropriate value can be selected from the alternatives defined here. In the uppermost row of this field, the user is asked to decide whether the drug is predominantly bound to either **albumin** or **alpha1-acid glycoprotein**. Depending on the predominant binding partner in plasma, the corresponding ontogeny function stored in PK-Sim® database will be used for scaling the plasma protein binding in children. If this information is not available or needed, you can also select **unknown** and the reference value selected in the simulation will be used irrespective of the age of the individual. In order to modify the fraction unbound as a function of disease please use the **Plasma protein scale factor** parameter defined in the **Individual building block**. With the help of this factor, the fraction of drug bound to either protein can be scaled up or down. The resulting fraction unbound parameter used in the simulation can be found in the list of parameters of the **Simulation** under the header **Distribution**. {% hint style="info" %} If the fraction unbound is known for one species, e.g., rat, but unknown for another one, e.g., dog, it is technically possible to simulate pharmacokinetics in the dog using the fraction unbound defined for the rat. In other words, PK-Sim® does not judge the consistence of the combination of the species and the fraction unbound. However, in this case the value should only be considered as a best guess and a reasonable variation around the fu values should be allowed. Similarly, for the scaling of pharmacokinetics from one species to another, make sure that not only the building block **Individual** is replaced but also mixed parameters such as fraction unbound in plasma and clearance pathways and/or expression data are changed appropriately. {% endhint %} #### **Molweight** In the first line the molecular weight (MW) of the substance is specified. For substances containing halogen atoms the number of these atoms should chosen from the drop down menu that can be opened next to the **Has Halogens** field. This input is used to calculate an *effective molecular weight*, which is needed to estimate the permeability values. It takes into account the small contribution of halogens to the molecular volume in relation to their weight. After the type and the number of halogens have been entered, the effective molecular weight is calculated automatically. {% hint style="info" %} Even though the property determining the diffusion coefficient is the molecular volume rather than the weight, only the latter is commonly available and has therefore been chosen as an easily accessible input parameter. However, in some cases this leads to inaccurate results, particularly since halogen atoms have a much smaller volume than what would be expected from their weight. Therefore, for substances containing such atoms, the “effective molecular weight” based on the following corrections is used (N = number of atoms, CF = correction factor): **Effective Molecular Weight** ![Image](/files/-LNl8Z4fKXS4_aYmKJTZ) with CF = 17 for fluorine, CF = 22 for chloride, CF = 62 for bromine, and CF = 98 for iodine (see \[[93](/references/references#93)]). {% endhint %} #### **Compound type / pKa** The type of compound: neutral, base, or acid. In case the compound is a base or an acid choose either **Base** or **Acid** from the drop-down menu. You will then be able to specify the respective pKa(s). Up to three pKa values can be specified. {% hint style="info" %} pKa values always refer to the pKa value of the acidic form of the compound. The compound type defines whether the pKa value refers to the uncharged acid "HA" (= type acid; the compound is charged when it dissociates to H+ and A-) or to the conjugated acid of a base "BH+" (= type base; the compound is uncharged when it dissociates to H+ und B). In other words, the compound type always refers to the uncharged form of the molecule. {% endhint %} {% hint style="info" %} The pKa values are used for the calculation of pH-dependent changes in solubility in the gastrointestinal tract. Furthermore, when using the distribution model (see [Creating new simulations in PK-Sim®](/working-with-pk-sim/pk-sim-documentation/pk-sim-simulations#creating-new-simulations-in-pk-sim)) of Rodgers and Rowland or the model of Schmitt, the compound type is a basic parameter for calculating the partition coefficients. It is furthermore used by the two charge-dependent methods of Schmitt to calculate the permeability of the barrier between interstitial and cellular space. {% endhint %} #### **Solubility** The solubility of the compound (in the intestine): The solubility can be specified together with the type of measurement or the medium used (first column, **Experiment**). The corresponding unit can be chosen from the drop-down menu in the second column (**Solubility at Ref-pH**). For charged compounds, the pH value at which the solubility of the compound was measured should be given in the third column (**Ref-pH**). In the fourth column, the **Solubility gain per charge** can be modified, which defines the factor by which the solubility increases with each ionization step. In order to calculate the charge of the molecule, the fraction of each microspecies is calculated according to the Henderson-Hasselbalch equation for a given pH. This is done across the entire pH-range such that the fractions are used to calculate the probability with which a molecule is in a certain ionization state. Based on this information, the **pH-dependent solubility** of molecules with one or more ionizable groups is calculated. By clicking on **Show Graph**, the pH-dependent solubility across the whole pH range calculated based on the experimental solubility at the defined pH is shown. For neutral compounds the input fields **Ref-pH** and **Solubility gain per charge** and the graph are irrelevant. {% hint style="info" %} In the simulation, the intestinal solubility can be displayed for each segment based on the inputs made here and the pH values in the gastro-intestinal tract of the individual used in the simulation. {% endhint %} {% hint style="info" %} The solubility of the compound is only needed for the oral administration route. Additionally, it can be taken into account if, e.g., a Noyes-Whitney dissolution is assumed for other routes of administration such as intramuscular or subcutaneous drug administration. However, for this purpose, the dissolution function has to be defined in MoBi®. {% endhint %} {% hint style="info" %} First estimates can be made using water solubility. However, especially for lipophilic compounds this value might underestimate the solubility in the intestine so that it is better to use a value obtained under bio-relevant conditions (e.g., in *Fasted State Simulated Intestinal Fluid*, FaSSIF). If different values are available for one compound (e.g., in FaSSIF and in *Fed State Simulated Intestinal Fluid*, FeSSIF), several alternative solubility values can specified and the appropriate value can then chosen in the **Simulation** creation step. {% endhint %} #### Intestinal solubility as table function of pH Intestinal solubility can also be defined as a linear interpolation of measured (pH, Solubility) data pairs. ![](/files/-LQ9BW8Lgn-eQVRAH1PS) ==> ![](/files/-LQ9BW8PaI6EQcgilbaS) ### ADME Properties tab After having defined the basic physico-chemical properties of the compound, processes known to be involved in its distribution and elimination can be specified in the **ADME** tab. The **ADME** tab is accessible either by clicking Next or by directly clicking on the respective tab in the **Create Compound** window. Five kinds of processes can be defined in the **ADME** tab depending on the type of interaction between the compound and the biological entity influencing the pharmacokinetics of the drug in vivo: * Absorption * Distribution * Metabolism * Transport & Excretion * Inhibition * Induction For each of these items one or more ADME processes can be defined in order to systematically collect all available information on absorption, degradation, transport, and binding processes from, e.g., in vitro assays and use this information to obtain specific kinetic rates used in the simulation. A general workflow for defining a specific process in *Protein Binding Partners*, *Metabolizing Enzymes*, *Total Hepatic Clearances*, *Transport Proteins*, *Renal Clearances*, and *Biliary Clearances* is as follows: * Right click on the biological process you want to add to (e.g. **Metabolizing Enzymes** in the **Metabolism** branch, **Renal Clearances** in the **Transport & Excretion** branch, …). * Click on the **Add …** command (e.g. **Add Metabolizing Enzyme …**). * Enter a name for the biological process you want to add. * Enter a name for the data source (e.g. in vitro assay, literature, laboratory results). * Select the process type from the list. * Enter the required input parameters (see tables below for an overview of the input parameters for each process type). * If physiological parameters are based on in vivo measurements, e.g. the intrinsic clearance, the respective species used in the experiment has to be selected. * Click **OK**. After definition of the required parameters the specific clearance or kinetic rate constant used in the simulation is automatically calculated taking into account the parameters listed under **Calculation parameters**. {% hint style="info" %} Specifying a value for **Specific clearance**, which is normally calculated automatically by PK-Sim®, will overwrite the original formula. This is indicated by the symbol . The formula can be reset by clicking on Image {% endhint %} After having defined the biological properties of the compound, you must link the specific processes to the enzymatic, transport, and binding settings defined for the selected individual/species in the Simulation. This is described in [Select relevant biological processes](/working-with-pk-sim/pk-sim-documentation/pk-sim-simulations#select-relevant-biological-processes). In the following, an overview of the process types is given that can be defined for the different biological properties, including additional information on the required input parameters. #### Absorption **Calculation of Specific Intestinal Permeabilities** PK-Sim® calculates the transcellular specific permeability of the intestinal wall is from the physico-chemical properties of a compound. In addition to the calculated specific intestinal permeability, experimentally determined permeabilities, e.g., from Caco-2-cell permeability assays, can be used. However, due to the large inter-laboratory variability in Caco-2 permeations, a proper calibration of the measured in vitro values and the calculated in silico permeabilities for a defined set of compounds is necessary. If the experimentally determined values for the intestinal permeabilities are available and the customized calibration method has been implemented in PK-Sim®, this option is then available in the drop-down menu in the *Calculation methods* window. **Specific Intestinal Permeability** Similarly, the specific intestinal permeability, i.e., the surface area-normalized transcellular permeability of the innermost layer of the intestinal wall, is calculated from the drugs´ lipophilicity and effective molecular weight. The paracellular pathway has been shown to have no impact on the accuracy of prediction of the fraction dose absorbed in humans \[[79](/references/references#79)] and is therefore not accounted for, i.e., the value for the paracellular specific permeability is not automatically calculated. However, the paracellular pathway can be included in the simulation, if desired. You will find the parameter **Intestinal permeability (paracellular)** in the simulation within the parameter group **Permeability**. In case that more than one lipophilicity value has been specified, all corresponding calculated permeability values are displayed in the drop down list that opens if you click on **Show Values**. Later, in the **Simulation**, you can select which lipophilicity value is to be used for the calculation of the specific intestinal permeability, or you can select the manually entered specific intestinal permeability. {% hint style="info" %} In contrast to the procedure for permeability of organ membranes, the relation between intestinal permeability and the molecular properties of the compound was generated using experimental fraction of dose absorbed values. It was optimized to provide the best prediction of total fraction absorbed (for details see \[[79](/references/references#79)]). {% endhint %} {% hint style="info" %} In the simulation parameters, the calculated specific intestinal permeability (transcellular) cannot be modified under the compound properties of the simulation. The appropriate simulation parameter can be found under the tree header "permeability". Please note that if the (calculated or manually entered) intestinal permeability (transcellular) is modified in the simulation, the permeability between the intracellular and interstitial space within the mucosa (`P (intracellular -> interstitial)`) will also automatically be scaled by the same factor. Otherwise, a disproportion between in the permeability of the apical and basolateral side of the enterocytes could be produced, leading to an accumulation of drug in the enterocytes. Likewise, a factor between the calculated intestinal permeability (transcellular) and an optional manual entry will be calculated to scale the permeability of the basolateral side of the enterocytes (`P (intracellular -> interstitial)`) appropriately. {% endhint %} {% hint style="info" %} If experimental values for intestinal permeability are available, e.g., from Caco2-cell permeability assays, a calibration of these in vitro values has to be performed for a defined set of compounds before they can be used as input parameters. This is due to the high inter-laboratory variability in absolute permeability values. In this calibration, the fractions of dose absorbed of the set of substances are correlated with the measured permeabilities. For new compounds, the corresponding intestinal permeability used in PK- Sim® is automatically calculated based on the Caco2 permeability value input. If you require an expert calibration of a defined set of experimentally determined permeabilities derived from in vitro assays, please contact your PK-Sim® support (). {% endhint %} For acids and bases, the transcellular intestinal permeability can be calculated dynamically along the gastrointestinal tract based on local luminal pH and the compound’s pKa. This option can be turned on in the simulation by enabling the switch **Use pH- and pKa-dependent penalty factor for charged molecule fraction** in the parameter group **Permeability**. When this option is enabled, the calculated specific intestinal permeability is multiplied by a penalty factor that accounts for the fraction of neutral species at the local pH in each GI segment. By default, PK-Sim keeps this option disabled because the original intestinal permeability model (Pint) was calibrated without this penalty term and using membrane affinity data measured at approximately neutral pH; enabling the penalty factor in that framework degraded prediction quality for the underlying calibration set. This design choice and its background have been discussed within the OSP community and development team (see discussions in OSP Forum [issue #25](https://github.com/Open-Systems-Pharmacology/Forum/issues/25) and [discussion #1816](https://github.com/Open-Systems-Pharmacology/Forum/discussions/1816)). Conceptually, only the neutral species is expected to permeate the phospholipid membrane effectively, and the neutral fraction varies with pH. A physiological basis for accounting for this is described by Willmann et al. \[[173](/references/references#173)], where GI absorption is driven by regional physiology and compound ionization. In practice, historical PK-Sim implementations used membrane affinity measured near pH 7.4 as a lipophilicity surrogate. Because those values (and logMA in general) show limited pH dependence, the pH effect on permeability was not explicitly applied in the default calibration. Subsequent internal evaluations indicated that simply turning on a uniform penalty for the charged fraction, on top of those neutral-pH-based inputs, could bias permeability downwards (sometimes up to an order of magnitude) and worsen predictions. **Recommendations** 1. Keep the penalty factor off when using permeability or membrane-affinity inputs that were derived or calibrated under neutral pH assumptions (default behavior), to remain consistent with the Pint calibration. 2. Consider enabling the penalty factor when permeability is intended to reflect pH-dependent lipophilicity (e.g., when using or estimating pH-dependent logD or a permeability input explicitly tied to the neutral fraction along the gut) so that the neutral-species limitation is respected regionally. 3. You can find the switch **Use pH- and pKa-dependent penalty factor for charged molecule fraction** in a simulation under the parameter group Permeability. Use it deliberately: enable it when your permeability input and modeling intent reflect pH-dependent neutral-species transport; keep it disabled to stay consistent with legacy neutral-pH–based calibration. {% hint style="info" %} This approach cannot be implemented in PK-Sim. You can export the simulation to MoBi and implement the pH-dependent lipophilicity there. {% endhint %} 4. As a more rigorous alternative, provide pH-dependent lipophilicity (logD) rather than pH-invariant membrane affinity as input and refit permeability accordingly. Expert guidance suggests distinguishing between membrane affinity and lipophilicity: for example, using logD of the neutral form for bases and approximately logD − 1 for acids as an approximation for membrane partitioning. This approach aligns better with the physiological rationale that permeability is driven by partitioning into the lipid core of membranes, which is inherently pH dependent (see Willmann et al., 2004). #### Distribution - Distribution calculation **Partition coefficient calculation methods** Two parameters determine the rate and extent of passive distribution in the body: steady state organ-plasma partition coefficients (PC) as well as permeability surface area (PxSA) products of each organ, also called Cellular Permeabilities (CP). The partition coefficients are calculated from the physico-chemical properties of the compound. **How are PC and CP predicted in PK-Sim®?** PBPK modeling requires many substance-specific parameters, which are usually unknown and rarely accessible directly. These include the organ/plasma partition coefficients, the permeability surface area products, and intrinsic clearances. The difficulty in gathering this type of data is one of the major reasons that prevented a more widespread use of PBPK-modeling in the past. PK-Sim® addresses and solves these issues by including several published and proprietary methods for calculation of PC and CP from physico-chemical data that are experimentally accessible and, in most cases, are frequently determined during the course of drug development. **How are organ/plasma partition coefficients deduced from physico-chemical parameters?** Organ/plasma partition coefficients are based on the concept of partition coefficients between drug binding tissue constituents and water. These include lipid/water and protein/water partition coefficients. Several similar concepts for utilizing such partition coefficients and the composition of organ tissue to calculate the organ/plasma partition coefficients have been published (see \[[53](/references/references#53)] and \[[86](/references/references#86)] for examples; an overview is given in \[[32](/references/references#32)]). Even though the idea is very similar in all cases, the different methods deviate in the kind of parameters that they use. PK-Sim® implements five different methods to calculate the partition coefficients for the organs: i) The PK-Sim® standard model, which is described in more detail below, and the approaches developed by ii) Rodgers & Rowland, iii) Schmitt, iv) Poulin & Theil, and v) Berezhkovskiy. The mechanistic equations for the different models are found in the respective literature (\[[53](/references/references#53)], \[[59](/references/references#59)], \[[62](/references/references#62)], \[[60](/references/references#60)], \[[61](/references/references#61)], \[[68](/references/references#68)], \[[54](/references/references#54)], \[[55](/references/references#55)], \[[52](/references/references#52)], \[[5](/references/references#5)]). In the PK-Sim® standard model \[[96](/references/references#96)] the partition coefficients are calculated using the following equation: *** ![Partition Coefficients](/files/-LNl8Z4u9LiueE-Vhg0V) with ![Image](/files/-LNl8Z4wBCcPk0WtGiWH) = volume fraction of water, lipid and protein, ![Image](/files/-LNl8Z54stb47uWXvUzO) = lipid/water partition coefficient, ![Image](/files/-LNl8Z57hVjcuqW_95A1) = protein/water partition coefficient, ![Image](/files/-LNl8Z52YN6ImiKji-d4) = free fraction in plasma. *** Partition coefficients are derived from input data as follows: ![Image](/files/-LNl8Z54stb47uWXvUzO) The value entered as **Lipophilicity** is directly used. ![Image](/files/-LNl8Z57hVjcuqW_95A1) Calculated from **Lipophilicity** using a correlation determined experimentally by measuring the unspecific binding to different tissue protein fraction of various organs for a large set of diverse compounds. Drug partitioning between plasma and red blood cells ($$K\_{rbc}$$) is calculated in analogous manner to ![Drug Partitioning](/files/-LNl8Z599BdFGbCVyJZJ) The only exceptions are the **Schmitt model** that additionally takes into account the amount of acidic and neutral phospholipids as well as neutral lipids, and the **Rodgers & Rowland** model, if experimental data for blood-to-plasma concentration ratios (B:P) are available. The equation for the calculation of $$K\_{rbc}$$ in the Schmitt partition model is: ![Drug Partitioning Schmitt](/files/-LNl8Z5BbZaD2HZKZR3K) If a value for B:P is used in the Rodgers & Rowland model, $$K\_{rbc}$$ is calculated as follows: ![Drug Partitioning Rodgers & Rowland](/files/-LNl8Z5E2_CJPimOUnD-) where HCT is the hematocrit and $$BP\_{ratio}$$ is the blood-to-plasma concentration ratio. No general rules have emerged to determine which distribution model is best suited based on the knowledge about the substance properties. However, some trends are contained within the different model foundations and assumptions as outlined below: | Partition coefficient calculation method | Description | | ---------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | PK-Sim® Standard (default) | The relevant compound parameters are lipophilicity and binding to plasma proteins. As lipophilicity measure, the membrane affinity (partition coefficient between water and an artificial membrane bilayer) is preferred in this model. The subcompartments of tissue and blood or plasma are assumed to consist of lipids, proteins, and water. Therefore the respective volume fractions as well as lipid/water ($$K\_{lipid}$$) and protein/ water ($$K\_{protein}$$) partition coefficients of the compound are considered. | | Rodgers & Rowland | In contrast to the previous model, this approach explicitly considers electrostatic interactions between ionized compounds (e.g. moderate-to-strong bases) and anionic phospholipids at physiological pH. It also considers interactions with intracellular neutral phospholipids and neutral lipids. Two additional input parameters are therefore necessary for the calculation of partition coefficients: the blood to plasma concentration ratio $$BP\_{ratio}$$, as a measure for electrostatic interactions of drugs with acidic phospholipids, and the vegetable oil-water partition coefficient ($$D\_{vo:w}$$) which is a better surrogate than the octanol-water partition coefficient ($$P\_{o:w}$$) for neutral lipids \[[59](/references/references#59)], \[[62](/references/references#62)], \[[60](/references/references#60)], \[[61](/references/references#61)]. | | Schmitt | This approach offers a universally applicable method to calculate organ-plasma partition coefficients under explicit consideration of electrostatic interactions between charged molecules at physiological pH and acidic phospholipids. pH differences between different subcompartments are taken into account, which leads to different amounts of dissociated and undissociated weak acids and bases. In contrast to the Poulin & Theil model the lipid subcompartment is assumed to consist of neutral lipids, neutral phospholipids and acidic phospholipids in order to better describe partitioning into biological membranes – especially of charged drugs. For each of these membrane constituents fractional volumes based on experimental literature data were used 68. | | Poulin & Theil | The approach developed by Poulin and Theil considers the cell lipid subcompartment as mainly consisting of phospholipids with a lipophilicity-hydrophobicity behavior similar to a mixture of 30 % neutral lipids and 70 % water. Organ-plasma partition coefficients are then calculated using the volume fractions of the aqueous ($$F\_w$$) and organic subcompartments ($$F\_{neutral\ lipid}$$ and $$F\_{phospholipid}$$) of the respective organ and plasma for this distribution model (select the combobox "advanced" in Individual --> Anatomy & Physiology and go to Physiology --> Tissue and body fluid physiology --> Tissue composition). For adipose tissue, vegetable oil-water partition coefficients ($$D\_{vo:w}$$) are used as lipophilicity measures, whereas octanol- water partition coefficients ($$P\_{o:w}$$) are used for non-adipose tissue \[[53](/references/references#53)], \[[54](/references/references#54)], \[[55](/references/references#55)], \[[52](/references/references#52)]. | | Berezhkovskiy | The assumptions made to describe drug partitioning into biological membranes as well as the input parameters correspond to those made in the Poulin & Theil model. However, peripheral drug elimination as well as drug exchange between compartments are considered, which leads to a modified version of the equation presented by Poulin and Theil \[[5](/references/references#5)]. | **Cellular permeability calculation methods** The rates of permeation across the cell membranes (interstitial-cell barrier) depend on the permeability surface area (PxSA) products of each organ. The permeability values (the part of the PxSA-products that is substance-dependent) are proportional to the permeability of a phospholipid bilayer for the simulated substance. They are calculated from the physico-chemical data of the compound currently active in the simulation. **How are permeability surface-area (PxSA) products predicted in PK-Sim®?** As a first approximation it can be assumed that all mammalian lipid membranes have the same permeability for a given substance. Of course this it not strictly true, because permeability depends on the composition of a membrane; the types of phospholipids and the content of cholesterol influence the rates with which a substance passes through the membrane \[[24](/references/references#24)] \[[9](/references/references#9)]. However, within the accuracy with which it is possible to estimate permeability from compound properties, it is permissible to make this simplifying assumption. Under these presumptions the PxSA-products are composed out of a compound specific term (permeability) and a species or physiology specific term (surface area). Because it is difficult to determine PxSA-products or their two components explicitly, the calculation method incorporated into PK-Sim® is based on the following procedure \[[36](/references/references#36)]: First, PxSA-products were previously determined by fitting simulations to experimental concentration-time curves for the different organs. Secondly, such pinned values are scaled by the organ volume to take the change of surface area, e.g. from species to species, into account. Furthermore, it is assumed that permeability is proportional to the partition coefficient and the diffusion coefficient, the latter of which depends on lipophilicity and molecular size for lipid membranes. This means, that permeability can be scaled with lipophilicity and molecular volume relative to given values. This is done in PK-Sim® using the values derived from the fit described above and dependencies which rely on published and proprietary knowledge. There are three different methods available in PK-Sim® to calculate the permeability parameters for the barriers between interstitial space and intracellular space which can be chosen from the drop-down menu: | Permeability parameters calculation method | Description | | ------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | PK-Sim® Standard (default) | With the method PK-Sim® Standard, the permeability parameters are calculated from the physico-chemical properties given in the Compound Data Window. The degree of dissociation of acids and bases is not taken into account. It is assumed that this value is the same in all organs and species and that differences originate only from size-dependent surface areas. | | Charge dependent Schmitt |

With this method, the degree of dissociation of acids and bases is taken into account assuming that the permeabilities for charged species are significantly smaller than for neutral species. The degree of dissociation is calculated from the pKa-values given for the Compound and the pH-values of the interstitial and intracellular spaces given. The permeabilities calculated with the method PK-Sim® Standard P0 are modified by a factor f(pKa- values, pH-value) accounting for the fractions of neutral/charged species:
Image
Since the pH-values of the interstitial and intracellular space differ for some organs, the permeability in the direction interstitial space -> intracellular space can differ from the permeability in the direction intracellular -> interstitial space.

| | Charge dependent Schmitt normalized PK-Sim® |

This method calculates the permeabilities in a similar way as dependent the method Charge Dependent Schmitt with the difference, that Schmitt the permeabilities are normalized to obtain the values calculated normalized to with the method PK-Sim® Standard:
Image
Thus, the permeability in the direction interstitial -> intracellular is the same as calculated with the method PK-Sim® Standard while the ratio of the permeabilities in the two directions is the same as calculated with the method Charge Dependent Schmitt.

| **Specific organ permeability** The specific organ permeability, i.e., the organ permeability normalized to the surface area, represents the part of the permeability times surface area (PxSA)- products that is substance-dependent and they are proportional to the permeability of a phospholipid bilayer for the simulated substance. They are calculated from the physico-chemical data of the compound, namely the lipophilicity and the effective molecular weight. If different lipophilicity values have been specified several permeability values based on these alternative values are displayed in the drop down list that opens if you click on **Show Values**. If available, further permeability values can be entered manually. You can later chose the lipophilicity value that is to be used in the **Simulation** from the values specified here. {% hint style="info" %} Because it is difficult to determine PxSA-products or their two components explicitly, the calculation method incorporated in PK- Sim® is based on the following procedure \[[36](/references/references#36)]: First, PxSA-products were previously determined by fitting simulations to experimental concentration-time curves for the different organs. Second, such pinned values are scaled by the organ volume to take the change of surface area, e.g. from species to species, into account. Furthermore, it is assumed that permeability is proportional to the partition and diffusion coefficient, the latter of which depends on the lipophilicity and molecular size for lipid membranes. This means that permeability can be scaled with lipophilicity and molecular volume relative to given values. This is done in PK-Sim® using the values derived from the fit described above and dependencies which rely on published and proprietary knowledge. {% endhint %} **Distribution - Specific Binding** Distribution of a compound is also influenced by specific binding to proteins either in plasma, the interstitial, or the intracellular spaces. It is possible to define such specific protein binding processes in the **Specific Binding -> Protein Binding** section. Right click on the entry "Protein Binding Partners" and select **Add Protein Binding Partner**. Select any of the proteins as binding partner and define the source (the "Data source" field will be added to the name of the created process). | Process Type | Description | Necessary Input Parameter | | ---------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------- | | Specific Binding | If experimental data on binding of the compound to specific protein binding partners are available, these values also suit as input parameters. | ![Image](/files/-LNl8Z5OnbfJe7f9LwMV) | {% hint style="info" %} Sometimes enzymes that catalyze a metabolic degradation process can also bind the compound at a binding site different to the catalytically active center. It is therefore possible to link an enzyme defined in the individual/species to both a metabolic and a binding process when setting up a simulation. {% endhint %} #### Metabolism Depending on the available experimental information you can either define process types in as **Metabolizing Enzymes** or as **Total Hepatic Clearance**. Please note that the calculations offered for metabolizing enzymes refer to the liver in case of intrinsic clearance processes and in all other cases to the organ in which the respective enzyme is expressed. Using this calculation sheet, input values will be transferred to specific clearance values which are then used in the simulation. The sheet is only meant to help the user with the calculations. However, processes defined here may also be applied to other organs given that relevant expression levels are appropriately defined in the individual. **Metabolizing Enzymes** The following process types can be defined in the **Metabolizing Enzymes** section: | Process Type | Description | Required Input Parameters | | -------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | Intrinsic clearance – First order |

A first order degradation process catalyzed by intracellular enzymes is defined in the liver. The input parameters are intrinsic clearance values which are either estimated or scaled from in vitro data. The specific clearance used in the simulation is obtained by scaling the intrinsic clearance value from liver cells to the whole organ using the following calculation parameters:

• Volume (liver) \[l]
• Fraction intracellular (liver)

|

• Intrinsic clearance (measured with liver cells or fitted) \[l/min]
• Volume(liver) \[l]
• Fraction intracellular (liver)

| | Intrinsic clearance – Michaelis-Menten |

A Michaelis-Menten type saturable kinetics process for intrinsic clearance. The input parameters are Km \[µmol/l] and Vmax \[µmol/l/min] (referring to the liver tissue, e.g., liver slices or perfused liver) which were either estimated or scaled from in vitro data.
The specific Vmax value used in the simulation (referring to the cellular volume) is scaled from the Vmax in liver tissue using the following calculation parameters:
• Fraction interstitial (liver)
• Fraction intracellular (liver)
The default value for Km is 1 μmol/l. Itmay be changed manually.

|

• Km \[µmol/l]
• Vmax \[µmol/l/min] (measured with liver tissue or fitted)
• Fraction interstitial (liver)
•Fraction intracellular (liver)

| | In vitro clearance – First order |

By explicitly defining specific clearance values referring to the cellular volume (either estimated or scaled from in vitro data) and the corresponding enzyme concentration a specific clearance value normalized to the enzyme concentration is calculated automatically.
The default value for enzyme concentration is 1 μmol/l. It may be changed manually.

|

• Enzyme concentration \[µmol/l]
• Specific clearance \[1/min] (measured with cellular in vitro system or fitted)

| | In vitro clearance – Michaelis-Menten |

You can also explicitly define specific Vmax values referring to the cellular volume (either estimated or scaled from in vitro data) to implement a Michaelis-Menten type saturable kinetics process. This value is then used to calculate kcat by normalizing the specific Vmax value to the respective enzyme concentration.
The default value for Km and the enzyme concentration is 1 μmol/l. It may be changed manually.

|

• Vmax \[µmol/l/min]
• Km \[µmol/l] (measured with cellular in vitro system or fitted)

| | In vitro clearance – Hill | Metabolic enzyme activity is described as saturable process displaying a cooperativity, which is characterized by the Hill equation. The corresponding kcat value is calculated from Vmax determined in an in vitro assay. |

• Enzyme concentration \[µmol/l]
• Vmax \[µmol/l/min]
• Km \[µmol/l]
• Hill coefficient

| | In vitro metabolic rate in the presence of recombinant CYPs/enzymes – First Order | Some in vitro assays use recombinant CYP enzymes to determine in vitro clearance values. These can be used as input for PK-Sim® after correction for the enzyme concentration in the assay when implementing a first order degradation process. Differences in intrinsic activity (per unit CYP)between rhCYP and human liver enzymes complicate the issue \[[63](/references/references#63)], \[[56](/references/references#56)]. | • In vitro clearance / concentration of recombinant enzyme \[µl/min/pmol rec. enzyme] | | In vitro metabolic rate in the presence of recombinant CYPs/enzymes – Michaelis-Menten | If Km and Vmax values for a saturable kinetics process were determined experimentally using recombinant CYP enzymes, Km can be directly used as for PK-Sim® where as Vmax has to be normalized to the enzyme concentration in the assay. Differences in intrinsic activity (per unit CYP) between rhCYP and human liver enzymes complicate the issue \[[63](/references/references#63)], \[[56](/references/references#56)]. |

• In vitro Vmax /concentration of the recombinant enzyme \[nmol/min/pmol rec. enzyme]
• Km \[µmol/l]

| | In vitro metabolic rate in the presence of liver microsomes – First Order | In vitro clearance values obtained from microsomal assays can be used as input parameters for definition of a first order metabolization process. If the clearance values are normalized to the amount of microsomal protein present in the assay they can be used without further modification.The in vitro clearance value is scaled to an in vivo specific clearance value using the content of CYP proteins in liver microsomes. The default value is 108 pmol/mg microsomal protein which is the CYP3A4 protein content in liver microsomes (see note under the table). Please change this value if other enzymes were defined. |

• In vitro clearance for liver microsomes \[µl/min/mg mic. protein]
• Content of CYP proteins in liver microsomes \[pmol/mg mic. protein] (e.g. \[63], \[64], or measured experimentally)

| | In vitro metabolic rate in the presence of liver microsomes – Michaelis-Menten |

For the definition of a saturable Michaelis-Menten like kinetics process in vitro Vmax values normalized to the enzyme concentration in the microsomal assay can be used as input parameter.
The in vitro Vmax value is then scaled to an in vivo Vmax value using the content of CYP proteins in liver microsomes. The default value is 108 pmol/mg microsomal protein which is the CYP3A4 protein content in liver microsomes (see note under the table). Please change this value if other enzymes were defined.

|

• In vitro Vmax for liver microsomes \[pmol/min/mg mic. protein]
• Content of CYP proteins in liver microsomes \[pmol/mg mic. protein] (e.g. \[63], \[64], or measured experimentally)
• Km \[µmol/l]

| {% hint style="info" %} For calculation of in vivo clearance or Vmax values from in vitro values obtained from microsomal assays, the content of the CYP enzyme defined as the process type has to be specified. The default value in PK-Sim® is 108 pmol/mg microsomal protein which is the CYP3A4 protein content in liver microsomes \[[63](/references/references#63)]. CYP enzyme contents in liver microsomes from this reference are shown when you move the mouse over the parameter Content of CYP proteins in liver microsomes. If you have defined other than these CYP enzymes, please insert the corresponding value in PK-Sim®. {% endhint %} **Definition of a metabolite in an enzymatic process** A metabolite of a compound can be defined and used either as a "sink" or treated like any other compound. See [How to set up a parent/metabolite simulation](/working-with-pk-sim/pk-sim-documentation/pk-sim-simulations#how-to-set-up-a-parentmetabolite-simulation) for details. **Total Hepatic Clearance** The following process types can be defined in the **Total Hepatic Clearance** section: | Process Type | Description | Necessary Input Parameter | | --------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Liver Plasma Clearance |

If you have experimental plasma clearance values you can use them by choosing this process type. The specific clearance used in the simulation is then automatically calculated on the basis of the following parameters:

• Body weight \[kg]
• Volume (liver) \[l]
• Hematocrit
• Blood flow rate (liver) \[l/min]
• Blood flow rate (portal vein) \[l/min]
• Fraction intracellular (liver)
• Fraction unbound (experiment)
• Lipophilicity
• Blood/Plasma concentration ratio
• Plasma clearance \[ml/min/kg]

The default value for fraction unbound (experiment) is 0.5 in PK-Sim®. Please change this parameter if you have experimental data for the fraction unbound in the experimental assay (not in plasma).

|

• Fraction unbound (experiment)
• Plasma clearance \[ml/min/kg]

All parameters listed in the left column (if not entered, default values as specified in the Compound building block for the given species are used)

| | In vitro hepatocytes – t1/2 |

You can use measured t1/2 values from hepatocyte assays. The specific clearance used in the simulation is then automatically calculated considering the following parameters:

• Number of cells/g liver tissue
• Number of cell/incubation
• Fraction intracellular (liver)
• Fraction unbound (assay)
• t1/2 (assay) \[min]

The default value for fraction unbound (assay) is 0.1 in PK-Sim®. Please change this parameter if you have experimental data for the fraction unbound.

|

<• Number of cell/incubation
• Fraction unbound (assay)
• t1/2 (assay) \[min]

| | In vitro hepatocytes – residual fraction |

If hepatocyte assay data with residual fractions are available, please specify these values in this process type. The specific clearance used in the simulation is then automatically calculated on the basis of the following parameters:

• Number of cells/g liver tissue
• Number of cell/incubation
• Fraction intracellular (liver)
• Fraction unbound (assay)
• Measuring time \[min]
• Residual fraction

The default value for fraction unbound (assay) is 0.1 in PK-Sim®. Please change this parameter if you have experimental data for the fraction unbound.

|

• Number of cell / incubation
• Fraction unbound (assay)
• Measuring time \[min]
• Residual fraction

| | In vitro liver microsomes – t1/2 |

t1/2 values from microsomal assays can be used as input parameters to calculate specific liver clearances. Scaling of the in vitro value is done using the following parameters:

• Microsomal protein mass/g liver \[mg/g]
• Amount of protein in the incubation \[mg/ml]
• Lipophilicity (experiment)
• Fraction intracellular (liver)
• Fraction unbound (assay)
• t1/2 (microsomal assay) \[min]

The value for fraction unbound (assay) is calculated in PK-Sim® using the lipophilicity of the compound and the amount of protein in incubation. Please change this parameter if you have experimental data for the fraction unbound.

|

• Amount protein/incubation \[mg/ml]
• Fraction unbound (assay)
• t1/2 (microsomal assay) \[min]

| | In vitro liver microsomes – residual fraction |

Residual fractions obtained from liver microsome assays may also serve as input parameters. The value for the specific liver clearance is then calculated using the following parameters:

• Microsomal protein mass/g liver \[mg/g]
• Amount protein/incubation \[mg/ml]
• Lipophilicity (experiment)
• Fraction intracellular (liver)
• Fraction unbound (assay)
• Measuring time \[min]
• Residual fraction \[%]

The value for fraction unbound (assay) is calculated in PK-Sim® using the lipophilicity of the compound and the amount of protein in incubation. Please change this parameter if you have experimental data for the fraction unbound.

|

• Amount protein/incubation \[mg/ml]
• Fraction unbound (assay)
• Measuring time \[min]
• Residual fraction

| {% hint style="info" %} Total hepatic clearance is a systemic process that does not have to be linked to properties defined in an individual/species when generating a simulation. {% endhint %} #### Transport & Excretion Drug transport across endothelial, epithelia, or cellular barriers is responsible for the distribution and renal or biliary elimination of a compound. Different experimental approaches are available either to determine rate constants or organ clearances. Depending on the experimental data available you can define different process types for your compound in the **Transport Proteins**, the **Renal Clearances**, or the **Biliary Clearance** section. **Transport Proteins** | Process Type | Description | Necessary Input Parameter | | -------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------ | | Intrinsic active transport - Michaelis-Menten |

A transporter-mediated transfer of a compound across a cellular membrane is described as saturable process following the Michaelis-Menten type kinetics. The specific Vmax value used in the simulation (referring to the cellular volume) is scaled from the Vmax in liver tissue using the following calculation parameters:

• Fraction interstitial (liver)
• Fraction intracellular (liver)

The default value for Km is 1 μmol/l. It may be manually changed.

|


• Km \[µmol/l]
• Vmax \[µmol/l/min]

| | Specific active transport - Michaelis-Menten | Here a Michaelis-Menten type saturable transport process is defined. The input parameters are Km and Vmax (either estimated or scaled from in vitro data). The kcat value used in the simulation is scaled from the input Vmax value by normalization to the transporter concentration. The default value for Km is 1 μmol/l. It may be manually changed. |

• Transporter concentration \[µmol/l]
• Vmax \[µmol/l/min]
• Km \[µmol/l]

| | Specific active transport - Hill | A transporter mediated transfer of a compound across a cellular membrane is described as saturable process displaying a cooperativity which is characterized by the Hill equation. The corresponding kcat value is calculated from a specific Vmax as input value. |

• Transporter concentration \[µmol/l]
• Vmax \[µmol/l/min]
• Km \[µmol/l]
• Hill coefficient

| | In vitro active transport (vesicular assay) - Michaelis-Menten | A transporter mediated transfer of a compound across a cellular membrane is described as saturable process following Michaelis-Menten type kinetics. The corresponding kcat value is calculated from a specific Vmax normalized to the amount of transporter as input value which was determined in a vesicular transport assay. |

• In vitro Vmax / transporter \[nmol/min/pmol transfer]
• Km \[µmol/l]

| **Renal Clearances** | Process Type | Description | Necessary Input Parameter | | ------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------- | | Kidney Plasma Clearance |

When choosing this process type, experimental values for kidney plasma clearance can be used as input parameters. The specific clearance used in the simulation is then automatically calculated on the basis of the following parameters:

• Body weight \[kg]
• Volume (kidney) \[l]
• Hematocrit
• Blood flow rate (kidney) \[l/min]
• Fraction unbound (experiment)
• Plasma clearance \[ml/min/kg]

The default value for fraction unbound (experiment) is 1 in PK-Sim®. Please change this parameter if you have experimental data for the fraction unbound.

|

• Plasma clearance \[ml/min/kg]
• Fraction unbound (experiment)

| | Glomerular Filtration | Filtration fractions are used in the case that the renal clearance differs from the GFR according to the properties of the individual. Please note that for small molecules this observation indicates that the compound is either actively reabsorbed or secreted, respectively. The GFR fraction can be used as a surrogate to compensate for active re-absorption (GFR fraction <1) or secretion (GFR fraction >1). The calculation of the resulting "GFR" is done when setting up the simulation. | • GFR fraction | | Tubular Secretion – First Order | For definition of a first order tubular secretion process you can use tubular secretion rates (either estimated or scaled from in vitro data). The specific tubular secretion rate is then calculated on the basis of the kidney volume. | • Tubular secretion \[l/min] | | Tubular Secretion – Michaelis-Menten | You can also define a saturable tubular secretion process by specifying Km and TSmax values (either estimated or scaled from in vitro data). The specific tubular secretion rate is then calculated taking into account the kidney volume. |

• TSmax \[µmol/min]
• Km \[µmol/l]

| {% hint style="info" %} Kidney Plasma Clearance is a systemic process that does not have to be linked to properties defined in an individual/species in a simulation. In the case of the Glomerular Filtration, the individual/ species-dependent GFR represents a default value defined in the Individual building block. {% endhint %} **Biliary Clearance** | Process Type | Description | Necessary Input Parameter | | ------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------- | | Biliary Plasma Clearance |

If you have experimental biliary plasma clearance data you can use them by choosing this process type. The specific clearance used in the simulation is then calculated automatically on the basis of the following parameters:

• Body weight \[kg]
• Volume (liver) \[l]
• Hematocrit
• Blood flow rate (liver) \[l/min]
• Blood flow rate (portal vein) \[l/min]
• Fraction intracellular (liver)
• Fraction unbound (experiment)
• Lipophilicity (experiment)
• Blood/Plasma concentration ratio
• Plasma clearance \[ml/min/kg]

The default value for fraction unbound (experiment) is 1 in PK-Sim®. Please change this parameter if you have experimental data for the fraction unbound.

The amount secreted as bile flow is subsequently split into two fractions: The fraction of hepatic bile that flows into the gallbladder for storage, and the fraction that flows straight into the duodenum.

|

• Plasma clearance \[ml/min/kg]
• Fraction unbound (experiment)

| {% hint style="info" %} Biliary clearance is a systemic process that does not have to be linked to properties defined for an individual/species when establishing a simulation. {% endhint %} ### Inhibition and induction Drugs may influence a broad variety of ADME processes that in turn will then affect the PK of the drug and possibly also other drugs. See section [PK-Sim® Compounds: Defining Inhibition/Induction Processes](/working-with-pk-sim/pk-sim-documentation/pk-sim-compounds-defining-inhibition-induction-processes) for details on how to define inhibition and induction processes in PK-Sim®. ### Advanced Parameters tab Additional compound-related parameters can be defined in the **Advanced Parameters** that are needed in case the particle dissolution function (see [Formulations](/working-with-pk-sim/pk-sim-documentation/pk-sim-formulations)) or the model for proteins and large molecules (see [Modeling of Proteins](/mechanistic-modeling-of-pharmacokinetics-and-dynamics/modeling-concepts/modeling-concepts-modeling-of-proteins)) are used. In all other cases, the parameters defined in the **Advanced Parameters** tab will not be used and can be left unchanged. #### **Particle dissolution** The particle dissolution function can be used for the simulation of the dissolution process of spherical particles administered orally and represents a dissolution function of the Noyes-Whitney type that is based on particle size \[[102](/references/references#102)]. The following parameters cane be specified: • How the precipitated drug is treated (either as Soluble or Insoluble) • The aqueous diffusion coefficient D • The density of the drug in its solid form • The maximum size of particles that dissolves immediately • Enable supersaturation or not. **Supersaturation** is the increase in the concentration of a solution beyond its saturation point. If activated, the effective concentration of the compound in the intestinal lumen can exceed its defined intestinal solubility. The default value of this option is 'disabled', meaning that supersaturation is inactivated. Further parameters such as the mean particle size and the particle size distribution, the number of bins, and the diffusion layer thickness are considered to be related to the formulation and thus can be defined in the Formulation Building Block (see [Formulations](/working-with-pk-sim/pk-sim-documentation/pk-sim-formulations)). #### **Model for proteins and large molecules** Four drug-related parameters which are used in the model for proteins and large molecules can be defined in the **Advanced Parameters** tab, namely: * **Radius (solute)**: The hydrodynamic radius of the drug. The default value for the solute radius is estimated from the molecular weight defined in the **Basic Physico-chemistry** tab. * **Kd (FcRn) in endosomal space:** the dissociation constant for binding to FcRn in the acidic endosomal space. By default, this value is set to a very high value, implying no binding. * **Kd (FcRn) in plasma/interstitial:** the dissociation constant for binding to FcRn in plasma and the interstitial space (neutral environment). By default, this value is set to a very high value, implying no binding. For monoclonal antibodies, the binding to FcRn in neutral environment is generally very weak or not detectable. In this case, the high default value for Kd (FcRn) in plasma/interstitial space can be kept. * **kass (FcRn):** the association rate constant for binding to FcRn in both the acidic endosomal space and the plasma/interstitial space. The default value is a typical value for monoclonal antibodies and can usually be kept as is. After all information about the compound properties has been entered, the **Create Compound** window can be closed by clicking **OK** . The new compound will appear in the **Building Blocks Explorer** view. ## Setting or Changing Compound Properties To set or change the properties of an existing compound: 1. Right mouse click on the respective compound in the **Building Blocks Explorer** 2. Select **Edit...** or simply double click on the compound in the **Building Blocks Explorer**. A window with the three tabs **Basic Physico-chemistry**, **ADME Properties**, and **Advanced Parameters** will open. The properties can be set or changed appropriately. The changes can be saved by closing the window by clicking on ![Image](/files/-LNl8Q5_I6QLMwPlc1Ju). ## Cloning Compounds To clone a compound in the project: 1. Right mouse click on the respective compound in the **Building Blocks Explorer** 2. Select **Clone...** 3. Enter an alternative name for the compound clone and enter a description, if desired. 4. Confirm and close the window by clicking **OK** ## Saving Compounds as Templates For each project, several compounds can be defined. They can be saved as templates and then shared among several projects and users. To save an existing compound as template: 1. Right mouse click on the respective compound in the **Building Blocks Explorer** 2. Select **Save as Template...** In case a compound with the same name already exists, a warning appears and you have the following options: * Override: This action will override the existing template. * Save as: You can save the compound under a different name. In this case, you will be asked to Rename the new template. * Cancel: This action will abort the saving process. ## Loading Existing Compounds from Templates As mentioned before, the compounds defined in a project can be saved as templates and then be shared among several projects and users. To load an existing compound from the template database: 1. Right mouse click on **Compounds** in the **Building Blocks Explorer** 2. Select **Load From Template...** 3. Select the desired compound from the user templates In case a compound with the same name already exists in the project, a warning pops up and you will have to **Rename** the compound that is to be loaded from template. 4. Click **OK** The selected compound will appear in the **Building Block Explorer** view. Compounds can also be directly loaded from the template database within a simulation. ## Deleting Compounds To delete a compound from the project: 1. Right mouse click on the respective compound in the **Building Block Explorer** 2. Select **Delete...** 3. Confirm by clicking **Yes** {% hint style="warning" %} Please note that a compound that is used in any simulation of the project cannot be deleted. {% endhint %} # Compounds: Defining Inhibition/Induction Processes Drugs may influence a broad variety of ADME processes that in turn will then affect the PK of the drug and possibly also other drugs. A specific and very common case of this very generic description of a drug-drug-interaction (DDI) is the inhibition of a metabolizing enzyme or a transporter. Most metabolizing enzymes are highly expressed in the liver and, therefore, drug clearance and the first pass metabolisms will be affected. Inhibition of a transporter may change the rate of absorption of a drug or the amount absorbed of a drug. If an inhibited transporter is expressed in the kidney or liver, drug excretion will be altered. The interaction processes in PK-Sim® are defined in the **ADME** tab of a compound. ## Inhibition Processes To set up an inhibition of a protein by a compound, do the following: * Right mouse click on *Inhibition* in the **ADME** tab of the compound that acts as an inhibitor and select *Add Inhibition Process*. * Select the affected enzyme/transporter and specify the source for assuming this inhibition. * Specify the type of inhibition from the Process type list (competitive, uncompetitive, non-competitive, mixed, irreversible/mechanism-based inactivation). The interaction types are described in the next sections. Inhibition changes reaction rates and/or the kinetics of active transports or metabolization reactions by modifying the following reaction and/or transport parameters: * The Michaelis-Menten constant $$K\_m$$ and the turnover number $$kcat$$ for Michaelis-Menten kinetics * The Specific Clearance for first order kinetics In case of a *Michaelis-Menten* process, the reaction/transport rate **without inhibition** is given by: $$v=\frac{V\_{max}\times S}{K\_M+S}$$ with $$V\_{max} = kcat \times E$$ is maximum velocity where $$kcat$$ is the rate constant and $$E$$ is the amount of enzyme/transporter, and $$S$$ = free substrate concentration. In an inhibition scenario, both, the turnover number kcat and the Michaelis- Menten constant, are modified to new apparent values: $$v=\frac{V\_{max,app}\times S}{K\_{M,app}+S}$$ with $$V\_{max,app} = kcat,app \times E$$ apparent maximum velocity which is the product of apparent $$kcat$$ and $$E$$, the amount of enzyme/transporter, and $$S$$ = free substrate concentration. PK-Sim® calculates the apparent $$kcat$$ and apparent Michaelis-Menten constant for the specified inhibition scenario. In case of a simple setting with just one inhibitor per process, the equations are listed in the next section. If first order processes are inhibited, the specific clearances will be altered. The generic expression for a reversible linear, non saturable metabolism/transport process of first order is: $$ {\huge \mathrm{CL}*{\mathrm{int,app}} = \mathrm{CL}*{\mathrm{int}} \left/ \left( 1 + \sum\_{a=1}^{m} \frac{I\_a}{K\_{I,a}} + \sum\_{c=1}^{o} \frac{I\_c}{K\_{I,c}} + \sum\_{d=1}^{p} \frac{I\_d}{K\_{Ic,d}} \right) \right.} $$ If an inhibition is set up for an enzyme or transporter, all processes with the same name will be linked and affected by the inhibition. An autoinhibition cannot be set-up because measured Ki values will already be altered due to autoinhibition. ![Metabolism or transport processes that are specified for a compound can be selected for inhibition.](/files/-LOWQ1kqrcVcg1ZKaZnk) ### Competitive inhibition - simple setting with one inhibitor In a competitive enzyme inhibition, the inhibitor binds reversibly to the enzyme and competes with the substrate for free enzyme. In case of a reversible inhibition, high substrate concentrations can overcome this inhibition. The apparent Michaelis-Menten constant increases while the apparent maximum reaction velocity remains unchanged. ![Schematic representation of a competitive inhibition](/files/-LNl8Za9mE89cGakOFps) $$v=\frac{V\_{max}\times S}{K\_{M,app}+S}$$ with $$v$$ = reaction velocity, $$V\_{max}$$ = maximum reaction velocity, $$K\_{M,app}$$ = apparent Michaelis-Menten constant, and $$S$$ = free substrate concentration. $$K\_{M,app}$$ is calculated as follows: $$K\_{M,app} = K\_M \times (1+\frac{I}{K\_I})$$ with the variables defined above and $$K\_M$$ = Michaelis-Menten constant in absence of an inhibitor, $$I$$ = free inhibitor concentration, and $$K\_I$$ = dissociation constant of the enzyme-inhibitor complex. ### Uncompetitive inhibition - simple setting with one inhibitor In a uncompetitive enzyme inhibition, binding of the inhibitor to the enzyme requires prior binding of the substrate to the enzyme. Binding of the inhibitor to the enzyme-substrate complex is reversible. This kind of inhibition decreases the apparent Michaelis-Menten constant and the maximum reaction velocity. ![Schematic representation of a non-competitive inhibition.](/files/-LNl8ZaUK73ZUoZ41Sff) The reaction rate is described by the following equation: $$v=\frac{V\_{max,app}\times S}{K\_{M,app}+S}$$ with $$V\_{max,app}$$ = apparent maximum reaction velocity, $$K\_{M,app}$$ = apparent Michaelis-Menten constant, and $$S$$ = free substrate concentration. The apparent maximum reaction velocity is decreased depending on the concentration of the inhibitor, and its affinity to the enzyme-substrate complex. $$V\_{max,app} = \frac{V\_{max}}{1+\frac{I}{K\_I}}$$ with $$V\_{max}$$ = maximum reaction velocity, $$I$$ = free inhibitor concentration, and $$K\_I$$ = dissociation constant of the enzyme-substrate-inhibitor complex. The apparent Michaelis-Menten constant is defined as follows: $$K\_{M,app} = \frac{K\_M}{1+ \frac{I}{K\_I}}$$ with the variables as defined above. ### Mixed Inhibition : Simple Setting with One Inhibitor In a mixed inhibition, the inhibitor binds reversibly to the enzyme or the enzyme/substrate complex with different affinities (and different dissociation constants). The inhibitor binding site is different from the substrate binding site on the enzyme molecule. The apparent Michaelis-Menten constant is changed and the apparent maximum velocity is decreased. ![Schematic representation of a non-competitive inhibition.](/files/-LNl8ZajQKizT_8y9aNP) The reaction rate is described by the following equation: $$v=\frac{V\_{max,app}\times S}{K\_{M,app}+S}$$ with $$V\_{max,app}$$ = apparent maximum reaction velocity, $$K\_{M}$$ = Michaelis-Menten constant in the absence of the inhibitor, and $$S$$ = free substrate concentration. The apparent maximum velocity is calculated as follows: $$V\_{max,app} = \frac{V\_{max}}{1+\frac{I}{K\_{Iu}}}$$ with $$V\_{max}$$ = maximum reaction velocity, $$I$$ = free inhibitor concentration, and $$K\_{Iu}$$ = dissociation constant of the enzyme-substrate-inhibitor complex. The apparent Michaelis-Menten constant is calculated as follows: $$K\_{M,app} = \frac{1+\frac{I}{K\_{Ic}}}{1+\frac{I}{K\_{Iu}}}$$ with $$K\_{Ic}$$ = dissociation constant of the enzyme-inhibitor complex, $$K\_{Iu}$$ = dissociation constant of the enzyme-substrate-inhibitor complex, and $$I$$ = free inhibitor concentration. ### Non-Competitive Inhibition : Simple Setting with One Inhibitor The non-competitive inhibition is a special case of a mixed inhibition in which an inhibitor binds reversibly to the enzyme and/or to the enzyme/substrate complex with the same inhibition constant ($$K\_I = K\_{Iu}=K\_{Ic}$$). The reaction velocity is described by the same equation as in a mixed inhibition and the apparent maximum velocity is described by the same equation as in an uncompetitive inhibition. ### Irreversible Inhibition / Mechanism-Based Inactivation Principally, an irreversible inhibition is a time-dependent inhibition (TDI) in which recovery is only due to de novo protein, e.g. enzyme synthesis. Thus, the in vivo production and degradation of enzyme has to be taken into account by PK- Sim®. Turnover of any protein inherently is a function of both, protein synthesis (a zero-order process) and protein degradation (a first-order rate process). In view of the kinetic nature of these processes, the rate constant of degradation frequently is the sole determinant of the "steady-state" concentration of each protein as it oscillates between the basal and the induced/repressed state. The natural enzyme turnover in PK-Sim® is represented as shown below. ![Enzyme E turnover (dEcat/dt) at steady state.](/files/-LNl8Zb0dwKZ9rxn5mEj) Initial enzyme concentration E0 and turnover rate constants kdeg are set to default values based on literature. The rate of inactivation follows a hyperpolic kinetic pattern. Generally, TDI has a slow onset, but potentially its effects are more profound than those of reversible inhibitions. The most prominent example of a practically irreversible inhibition is the inactivation of CYP-mediated reactions in the presence of NADPH. A common model for mechanism-based inactivation is illustrated below: ![Schematic representation of a enzyme inhibition by a mechanism-based enzyme inactivator](/files/-LNl8Zb2PpFP_YFBcBrN) According to Silvermann et al. \[[72](/references/references#72)], a mechanism-based enzyme inactivator (MBEI) requires a step to convert the compound to the inactivating species (k2). This step, which is generally responsible for the observed time dependence of the enzyme inactivation, usually is irreversible and forms a new complex (EI') which can have two distinctive fates: * The EI' is a reactive species and forms a covalent complex with the enzyme (Einact) (k4). * The species generated is released from the enzyme as a product/metabolite P of the inactivator and the enzyme is again available as active enzyme (k3). The ratio of product release to inactivation is termed the partition ratio and represents the efficiency of the mechanism-based inactivator: the partition ratio is described by k3/k4. The two principal kinetic constants that are useful in describing mechanism-based inactivation are **kinact** (the maximum rate of inactivation) and **Kkinact\_half** (in literature also often referred to as KI, the concentration at which the inactivation rate is half-maximal). Based on the reaction scheme shown above and with the typical assumption of quasi steady-state, it can be shown that **kinact** is a complex mixture of k2, k3, and k4, while **Kkinact\_half** is a complex mixture of k1, k-1, k2, k3, and k4: ![kinact is the maximum rate of inactivation](/files/-LNl8Zb452fSqQFrvrWk) ![Kkinact\_half is the concentration at which the inactivation is half-maximal](/files/-LNl8Zb6XuzPoss3J7Se) The implementation in PK-Sim® of one mechanism-based inactivator follows the equation shown below: ![Enzyme E turnover (dEcat/dt) in the presence of one inhibitor I.](/files/-LNl8Zb86KV7PV7fx9Av) Note that irreversible inhibition in PK-Sim® also always includes reversible binding of the mechanism-based inactivator to the enzyme so that it also acts as a competitive inhibitor. This process is defined by its dissociation constant Ki. By default (assuming the mechanism-based model based on \[[72](/references/references#72)]), Ki equals Kkinact\_half. The user may choose a different value if applicable. If more than one compound other than the mechanism-based inactivator competes for the binding at the enzyme, this can easily be implemented by specifying for the respective compound a reversible (e.g. competitive) inhibition process. This process automatically accounts for the so called **substrate protection of the enzyme**. An example where there is one substrate and one mechanism-based inactivator simultaneously competing for the binding site is illustrated below. ![Schematic representation of an enzyme (E) inhibition by a mechanism-based enzyme inactivator I in the presence of a substrate S. E converts I into a metabolite P and S into M, additionally the inactivator inactivates irreversibly the Enzyme.](/files/-LNl8ZbAOGuIMelR4X0L) This model could be represented in PK-Sim® as follows ![Simultaneous modeling of mechanism-based inactivation by the Inhibitor I, competitive inhibition by the Inhibitor I and substrate protection. Upper equation: enzyme turnover; lower equation: substrate depletion rate via the respective enzyme.](/files/-LNl8ZbCUO7a7wIH8qq9) Note that substrate protection can only be modeled by specifying a reversible inhibition process for the substrate (enter a Ki value). {% hint style="info" %} Given the variability and uncertainty associated with experimental determination of enzyme turnover rates, a sensitivity analysis for the enzyme half life should be considered in the modeling approach. {% endhint %} {% hint style="info" %} Please note that for the mechanism-based inactivator no clearance process is defined via the inactivation process by default. In theory, for every inactivated enzyme molecule, also one inactivator molecule is cleared; this must be separately defined by the user in form of additional metabolization/excretion processes for the inhibitor. {% endhint %} ## Protein Induction Enzyme or transporter induction can occur as a result of either increased **de novo synthesis of protein** or (in very rare cases and currently not implemented in PK-Sim®) a decrease in degradation following protein stabilisation induction. Some examples of induction processes are: * CYPs 1A1, 1A2 and 1B1 induced by aryl hydrocarbon receptor (AHR) that is activated by binding of e.g. dioxin, benzoapyrene, omeprazole (in vitro), tobacco smoke * CYP3A induced primarily by pregnane X receptor (PXR) that is activated by binding of e.g. rifampicin, phenobarbital, nifedipine * Activation of the pregnane X receptor induces a number of Phase II enzymes involved in drug metabolism as well as numerous transporters Implementation of induction in PK-Sim® uses the following parameters: * Emax: maximum in vivo induction effect (Dimension: dimensionless) * EC50: concentration of the inducer to reach half the maximal in vivo induction effect (Dimension: concentration) In an induction, Emax ranges from 0 (= no induction) to infinity. A value of 1 means that the effect is twice the effect without induction. Modelling of suppressed de novo synthesis (suppression) (for example in some cytokines) is also possible with PKSim using the induction specification of a compound. In a suppression, Emax ranges from 0 (=no suppression) to -1 (full suppression, no synthesis anymore). If the reaction of the enzyme Ex and the substrate Sj follows a Michaelis-Menten kinetics, the rate of the enzyme Ex degradation/production and the substrate Sj degradation are given by: ## Multiple Inhibitors : Equations Used by PK-Sim® The enzyme turnover for Enzyme X in the presence of m competitive (CI), n uncompetitive (UI), o non-competitive (NI), p mixed-type inhibitors (MI), q mechanism-based enzyme inactivators/time dependent inactivators (TDI) and r inducers (IND) is given by: ![Enzyme Ex turnover (dEx/dt) at steady state in the presence of m competitive (CI), n uncompetitive (UI), o non-competitive (NI), p mixed-type inhibitors (MI), q mechanism-based enzyme inactivators/time dependent inactivators (TDI) and r inducers (IND).](/files/-LNl8ZbEPMRad1XUzQPB) If the reaction of the enzyme Ex and the substrate Sj follows a Michaelis-Menten kinetics, the rate of the substrate Sj degradation is given by: ![Substrate Sj degradation dSj/dt) at steady state in the presence of m competitive (CI), n uncompetitive (UI), o non-competitive (NI), p mixed-type inhibitors (MI), q mechanism-based enzyme inactivators/time dependent inactivators (TDI) and r inducers (IND).](/files/-LNl8ZbGGDCUwISH_XWJ) In the above equation, the substrate Sj may also be an inhibitor of all kind, e.g. CI, UI, NI, MI, TDI or IND. Similarly, if the reaction of the enzyme Ex and the substrate Sj follows a first order kinetics, the rate of the enzyme Ex degradation/production and the substrate Sj degradation are given by: ![Enzyme Ex turnover (dEx/dt) at steady state in the presence of m competitive (CI), n uncompetitive (UI), o non-competitive (NI), p mixed-type inhibitors (MI), q mechanism-based enzyme inactivators/time dependent inactivators (TDI) and r inducers (IND).](/files/-LNl8ZbIiU706a7zQ9JX) ![Substrate Sj degradation dSj/dt) at steady state in the presence of m competitive (CI), n uncompetitive (UI), o non-competitive (NI), p mixed-type inhibitors (MI), q mechanism-based enzyme inactivators/time dependent inactivators (TDI) and r inducers (IND).](/files/-LNl8ZbK585BWWrUzwS4) In the above equation, the substrate Sj may also be an inhibitor of all kind, e.g. CI, UI, NI, MI, TDI or IND. Please note that * As for all other inhibition types, there is no reversible auto-inhibition (which means: if a compound is substrate and reversible inhibitor of the same enzyme, it does not appear in the Km\_interaction\_factor.) In the formula above it's done by excluding the substrate from the sum terms (a#j, b#j, etc.). * For mechanism-based inactivators auto-inhibition can be accounted for by specifying a specific clearance pathway via the affected enzyme. * Free (unbound) concentrations of all inhibitors are used (e.g. TDI\_u,l(t) means: unbound concentration of TDI\_l). # Administration Protocols An administration protocol is a set of data describing administration type, dose, and dosing regimen. These properties can be specified within the building block **Administration Protocol** . Administration protocols can be saved as templates and shared among other projects and users. ## Definition of new Administration Protocols in PK-Sim® To create a new administration protocol, do one of the following: * Click **Administration Protocol** in the **Create** Group of the **Modeling** Tab, or * Right mouse click on **Administration Protocols** in the **Building Blocks Explorer** and select **Add Administration Protocol...**, or * Use the short cut **Ctrl+Alt+A** A new window will open where you can define your administration protocol. You can choose between **Simple protocol** and **Advanced protocol**. To switch between these two views, select the respective protocol type in the uppermost checkboxes of the window. {% hint style="warning" %} Note that when switching between simple and advanced protocol, some of the already defined parameters will be **reset**. When switching from simple to advanced protocol, the dosing schedule will be transferred. This is not true for the opposite direction. {% endhint %} **Simple protocol**, drug administration via different routes can be defined by means of a single or predefined multiple dosing scheme. **Advanced protocol**, multiple dosing regimens and treatment cycles of any scheme and combination can be defined. The default is the **Simple Protocol** . In both options, the dose and dosing scheme are visualized in the lower panel of the window. Depending on the dose unit selected, the Y-axis description will change accordingly. The administration protocol is initialized by providing it a **Name** in the respective input field. The name is used to identify the protocol when its parameters are saved in the project and/or as a template. Then, choose between **Simple protocol** and **Advanced protocol** and set the properties of the protocol. ### Simple Protocol To create a **Simple Protocol**, follow the instructions in the table below. Depending on the choice of administration protocol the required input parameters change. | Administration Type | Description | | ------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Intravenous Bolus |

1. Select the administration type Intravenous Bolus from the drop-down menu
2. Enter the dose and select the appropriate dose unit from the drop-down menu
3. Select the appropriate dosing interval from the drop-down menu
4. In case a multiple dosing regimen is selected, the protocol end time has to be defined.
5. Confirm and close window by clicking OK

| | Intravenous Infusion |

1. Select the administration type Intravenous Infusion from the drop-down menu
2. Enter the dose and select the appropriate dose unit from the drop-down menu
3. Select the appropriate dosing interval from the drop-down menu
4. In case a multiple dosing regimen is selected, the protocol end time has to be defined.
5. Enter the infusion time and select the appropriate time unit from the drop-down menu
6. Confirm and close window by clicking OK

| | Oral |

1. Select the administration type Oral from the drop-down menu
2. Enter the dose and select the appropriate dose unit from the drop-down menu.
3. Select the appropriate dosing interval from the drop-down menu.
4. In case a multiple dosing regimen is selected, the protocol end time has to be defined.
5. Enter the volume of water co-administered. The default is 3.5 mL/kg body weight, which corresponds to a volume of 250 mL (8-9 fl. oz.) of water for an average human. This volume is also considered appropriate in animal dosing \[103]. However, if desired, the liquid volume can be adjusted according to the protocol of the (pre)clinical study.
6. Confirm and close window by clicking OK

| {% hint style="info" %} Please note that if the administration type **Oral** is selected this will require the definition of a **Formulation** in the **Formulation** building block for the Simulation. {% endhint %} | Administration Type | Description | | ---------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | User Defined |

1. Select the administration type User Defined from the drop- down menu
2. Enter the dose and select the appropriate dose unit from the drop-down menu.
3. Select the appropriate dosing interval from the drop-down menu.
4. In case a multiple dosing regimen is selected, the protocol end time has to be defined.
5. Enter the target organ into which the drug is to be administered, e.g., Muscle in the case of intramuscular administration.
6. Enter the target compartment within the target organ into which the drug is to be administered, e.g., "Interstitial" in the case of intramuscular administration.
7. Confirm and close window by clicking OK

| {% hint style="info" %} Please note that in case that the administration type **User Defined** is selected this will require the definition of a **Formulation** in the **Formulation** building block for the Simulation. {% endhint %} ### Advanced Protocol Activate **Advanced protocol** in the **Create Administration Protocol** window. In the uppermost drop-down menu, the time unit for visualization of dose and dosing scheme in the lower panel of the window can be selected. Depending on the dose unit(s) selected, the Y-axis label(s) will change appropriately. The table used to defined the advanced protocol consists of the following five columns: 1. The **Start Time** at which the protocol schema starts. 2. The **Number of Repetitions** defining the iterations of the protocol schema. 3. The **Time Between Repetitions** defining the time lag between the iterations of several protocol schemata. 4. The **End Time** defining the end time of the protocol schema. The end time is automatically calculated based on the input parameters. 5. In the last column, additional protocol schemata can be added by clicking ![Image](/files/-LNl8RByZbYsQsNb5Xvn) or deleted by clicking ![Image](/files/-LNl8RsPTW2x1Ae9es_5). Please note that at least one protocol schema needs to be defined. The various protocol schemata will automatically be re-sorted according to the protocol schema start time. The secondary table, can be opened by clicking ![Image](/files/-LNl8RByZbYsQsNb5Xvn) in the column **Start Time**, a number of individual schema items can be defined for the given protocol schema. The following five columns can be found: 1. The **Start Time** of schema items in relation to the start time of the protocol schema. If the start time of the schema items is **0**, the administration time equals the start time of the protocol schema. 2. The **Dose** in units mg or mg/kg of the drug administered. 3. The **Administration type**. You can choose from the following administration types from the drop-down menu: * Intravenous Bolus * Intravenous Infusion: requires the input of the **Infusion time** in units min, h, or s * Oral: requires the input of the **Volume of water/body weight** co- administered, which is 3.5 mL/kg BW per default (see PK- Sim® - *Formulations*) and, additionally, the definition of a **Placeholder for formulation** in column 4. 4. **Placeholder for Formulation**.\ For an intravenous administration (Intravenous Bolus and Intravenous Infusion), the definition of a formulation placeholder is not necessary, because the drug is always assumed to be dissolved when given intravenously (see [PK-Sim® - Formulations](/working-with-pk-sim/pk-sim-documentation/pk-sim-formulations)). In case of oral and user defined administration, you should add a note on the type of formulation. Later, in the simulation, the formulation placeholder can be matched with the corresponding **Formulation** building block. This may sound trivial in the case of only one formulation given repeatedly at the given times. However, consider that you can set up sophisticated dosing schedules, in which various administration types and formulations are administered at various times. Then, the formulation type should already be signified in the administration protocol in order to be able to appropriately match the schedules with the various formulations. For further information please see [PK-Sim® - Simulations](/working-with-pk-sim/pk-sim-documentation/pk-sim-simulations). 1. In the last column, additional dosing schedules can be added or deleted by clicking. Please note that at least one dosing schedule needs to be defined for each protocol scheme. The various schema items will automatically be re-sorted according to the schema item start time. **Example** In the following screenshot, an example of an advanced protocol is given. The protocol example consists of only one protocol scheme. However, the protocol schema is repeated after 24 hours. Within one repetition, the drug is administered three times: first, an intravenous bolus loading dose of 1 mg/kg is given; second, an immediate release (IR) tablet containing 50 mg of drug is given 2 hours later; third, an enteric coated (EC) tablet containing 50 mg of the drug is given 12 hours after the intravenous dose, i.e. 12 hours after the beginning of the protocol schema. The dissolution profiles of the two formulation types have to be defined in the **Formulation** building block. The formulations can be imported and linked to the corresponding administration time points during the generation of the simulation. Here, only a "placeholder" has to be defined that can be used during the generation of the simulation to identify the different tablet types and thus, to appropriately match the administration time points and the formulation types. Since the last dose within the protocol items is administered after 12 hours and the protocol schema is repeated two times with a time between the repetitions of 24 hours, the last dose is administered after 24 + 12 = 36 hours (**End Time** of the protocol schema). This is also shown in the lower panel of the window. ![The Create Administration Protocol dialog. Here, the example of an individually created advanced protocol is shown.](/files/-LNl8UNGjV2zjceAw_-x) {% hint style="info" %} Please note that the combination of the Administration type **User defined** and the **Advanced protocol** is not available. {% endhint %} ## Setting or Changing Administration Protocol Properties To set or change the properties of an existing administration protocol: 1. Right mouse click on the respective administration protocol in the **Building Block Explorer** 2. Select **Edit...** or **Double click** on the administration protocol in the **Building Block Explorer** A window with the current settings will open where properties can be set appropriately. The changes are saved by closing the window by clicking on ![Image](/files/-LNl8Q5_I6QLMwPlc1Ju). {% hint style="warning" %} Please note that when you switch between simple and advanced protocol, this action will reset several parameters already defined. However, when switching from simple to advanced protocol, the dosing schedule will be transferred. This does not apply to the opposite direction. {% endhint %} ## Cloning Administration protocols To clone a protocol in the project: 1. Right mouse click on the respective protocol in the **Building Block Explorer** 2. Select **Clone...** 3. Set an alternative name for the protocol clone and, if desired, enter a description 4. Confirm and close the window by clicking **OK** ## Saving an Administration Protocols as Templates For each project, a number of administration protocols can be defined. They can be saved as a template and then be shared among several projects and users. To save an existing administration protocol as template: 1. Right mouse click on the respective administration protocol in the **Building Block Explorer** 2. Select **Save as Template...**. If a protocol with the same name already exists, a warning appears and you have the following options: * **Override**: This action will override the existing template. * **Save as**: You can save the protocol under a different name. In this case, you will be asked to **Rename** the new template. * **Cancel**: This action will abort the saving process. ## Loading Existing Administration Protocols from Templates To load an existing administration protocol from the template database: 1. Right mouse click on **Administration Protocols** in the **Building Block Explorer** 2. Select **Load From Template...** 3. Select the desired administration protocol from the user templates. In case a protocol with the same name already exists in the project, a warning appears and you will have to **Rename** the protocol that is to be loaded from template. 4. Click **OK** The selected administration protocol will appear in the **Building Block Explorer**. Administration protocols can also be directly loaded from the template database within a simulation. ## Deleting Administration Protocols To delete an administration protocol from the project: 1. Right mouse click on the respective administration protocol in the **Building Block Explorer** 2. Select **Delete...** 3. Confirm by clicking **Yes** {% hint style="warning" %} Please note that a protocol that is used in any simulation of the project cannot be deleted. {% endhint %} # Formulations In the building block **Formulation** the properties of the dosage form that is administered can be defined. Most of the predefined formulations are related to formulations typically administered via the oral route, whereas others, such as the **Zero Order** and the **First Order** release functions, can technically be administered into any other compartment. Please note that not all combinations of formulations and administration routes are possible. For an intravenous administration (bolus and infusion), formulation is not required as a drug administered intravenously is assumed to be dissolved in a medium. ## Definition of new Formulations in PK- Sim® To create a new formulation, do one of the following: * Click on **Formulation** in the **Create** Group of the **Modeling** Tab, or * Right mouse click on **Formulations** in the **Building Block Explorer** and select **Add Formulation...**, or * Use the short cut **Ctrl+Alt+F**. A dialog will open where the properties of the formulation can be defined. The formulation is initialized by giving it a **Name** in the respective input field. The name is used to identify the formulation when its parameters are saved in the project and/or as a template. The name is also used for identification of the formulation in the simulation. For the different types of empirical or user-defined release functions, the dissolution curve will be depicted in the adjacent graph as fraction of dose dissolved *vs.* time. For **Particle Dissolution**, the dissolution function represents the result of the mechanistic dissolution model of the Noyes- Whitney type in combination with the physiological conditions, rather than an input function. Thus, the dissolution properties do not only change as a function of the physico-chemical properties of the drug and the formulation characteristic, but also with the physiological conditions of the individual or animal. The resulting fraction dissolved as a function of time within the intestinal segments represents a simulation output that can be displayed in the **Results Window** of the simulation (see [Shared Tools - Chart Component](/shared-tools-and-example-workflows/chart-component)). From the drop-down menu you can choose from the following predefined formulations: * Dissolved * Weibull * Lint80 * Particle Dissolution * Table * Zero Order * First Order In the following sections, the different formulation types are described in more detail. ### Dissolved Using this type of formulation the drug is assumed to be administered in solution. Therefore, the whole amount of drug becomes available for absorption directly after the administration. {% hint style="info" %} The formulation type **Dissolved** characterizes the drug as being in solution at the point of administration. However, in case of poorly soluble compounds the intestinal absorption may be limited by the solubility, with the solubility (or in case of ionizable compounds the local pH-dependent GI solubility calculated using to the Henderson-Hasselbalch equation), imposing an upper bound to the absorption rate. {% endhint %} ### Weibull The Weibull function can be used to empirically (i.e., not mechanistically) describe the dissolution behavior of various dosage forms. The Weibull function can fit almost any kind of dissolution curve and is often used to describe experimental data when the mechanism of the release is not known \[[7](/references/references#7)] \[[30](/references/references#30)]. When applied to drug dissolution and release from pharmaceutical dosage forms, the Weibull function expresses the accumulated fraction of the drug $$m$$ in solution at a time $$t$$ according to the following equation \[[40](/references/references#40)]: $$m=1-\exp(\frac{-(t-T\_{lag})^b}{a})$$ where $$a$$ is the scale parameter, defining the time scale of the process, $$T\_{lag}$$ the lag time before the onset of the dissolution or the release process, and $$b$$ the shape parameter characterizing the curve as either exponential ($$b = 1$$), sigmoid ($$b > 1$$), or parabolic ($$b < 1$$). The following parameters have to be defined when choosing the Weibull function: * **Dissolution shape** $$b$$ characterizing the curve as either exponential ($$b = 1$$), sigmoid ($$b > 1$$), or parabolic ($$b < 1$$). * **Dissolution time (50% dissolved)** defining the time (excluding the lag time) at which 50% of the administered dose is dissolved and, thus, corresponding to the scale parameter $$a$$ of the Weibull function. * **Lag time** $$T\_{lag}$$ characterizing the time after which dissolution begins. * **Use as suspension**: if selected, the formulation will disintegrate in the stomach and the disintegrated particles will migrate along the gastrointestinal tract compartments. Particle dissolution formulation is always treated as a suspension per construction. If, on the other side, this option is not selected, the tablet will be treated as nondisintegrating tablet with discrete transition in the different intestinal compartments. Please note that the Weibull function can only be combined with the Administration type **Oral**. ### Lint80 The **Lint80** is an empirical function assuming linear release until 80% of the administered dose is dissolved. This type of formulation can only be combined with the Administration type **Oral**. The following parameters have to be defined when choosing the **Lint80** function: * **Dissolution time (80% dissolved)**, defining the time (excluding the lag time) when 80% of the administered dose is dissolved. * **Lag time** characterizing the time after which dissolution starts. * **Use as suspension**: if selected, the formulation will disintegrate in the stomach and the disintegrated particles will migrate along the gastrointestinal tract compartments. Particle dissolution formulation is always treated as a suspension per construction. If, on the other side, this option is not selected, the tablet will be treated as nondisintegrating tablet with discrete transition in the different intestinal compartments. ### Particle Dissolution Particle Dissolution calculates the dissolution kinetics of spherical particles with a predefined particle size distribution based on the Noyes-Whitney approach. The details of the mechanistic dissolution model have been described by Willmann et al \[[102](/references/references#102)]. In PK-Sim®, the particle dissolution can only be combined with the Administration type **Oral**. To simulate the particle size dependent dissolution, the following formulation-dependent parameters have to be defined: * **Thickness (unstirred water layer)** - thickness of the diffusion layer. * **Type of particle size distribution** - monodisperse or polydisperse. * **Particle radius (mean)**. For the **polydisperse** type of particle size distribution, the following additional parameters can be defined: * **Particle size distribution**: either normal or log normal. * **Particle radius (min)**: the lower limit for the particle radius. * **Particle radius (max)**: the upper limit for the particle radius. * **Number of bins**. For **normal** distribution: * **Particle radius (mean)** * **Particle radius (SD)**: Standard deviation of the particle radius. For **log normal** distribution: * **Particle radius (geomean)**. * **Coefficient of variation**. In addition, in order to use the Particle Dissolution formulation, the drug-related parameters have to be defined in the **Advanced Parameters** tab of the **Compound Building Block**. These include: * **Aqueous diffusion coefficient**. * **Density of the drug** material, and the threshold for immediate dissolution. Further, you will have to indicate how the precipitated amount should be treated (either as soluble or insoluble). ### Table Table defines the amount of drug applied per unit time as a continuous function. You can either manually specify time and fraction of the applied dose values or import dissolution data from Excel®. In order to manually enter the values: * Click on **Add Point** ![Image](/files/-LNl8RByZbYsQsNb5Xvn) to add a new row to the table * Enter appropriate values for **Time** and **Fraction (dose)** dissolved {% hint style="info" %} The origin (0, 0) is always present. Values must be monotonically increasing in the **Time** column. The resulting function will be represented in the adjacent graphic. The absolute dose will be taken from the respective **Administration Protocol Building Block** that will later be used in the simulation. {% endhint %} In order to **import** experimental dissolution data from Excel®: 1. Click **Import Formulation** 2. Select and open the Excel® file 3. Import and transfer the appropriate Excel® sheet {% hint style="info" %} For additional information about the import data and mapping workflow see [Import and Edit of Observed Data](/shared-tools-and-example-workflows/import-edit-observed-data). {% endhint %} * **Use as suspension**: if selected, the formulation will disintegrate in the stomach and the disintegrated particles will migrate along the gastrointestinal tract compartments. Particle dissolution formulation is always treated as a suspension per construction. If, on the other side, this option is not selected, the tablet will be treated as nondisintegrating tablet with discrete transition in the different intestinal compartments. ### Zero Order Zero Order defines the application at a constant rate. The total dose (defined in the administration protocol) will be administered at a constant rate until within the specified time \[Start of administration, Start of administration + **(End time)**]. ### First Order First Order defines the application as a first order input. The required input is the half-life of application value **(t1/2)**. The formulation release is then described by the following equation: $$\frac{dA}{dt}=-k\cdot A$$ where $$A$$ is the amount of drug at time $$t$$ and $$k$$ the first order rate constant calculated from the half-life of application value according to: $$k=\frac{\ln(2)}{t\_{1/2}}$$ ## Setting or Changing Formulation Properties To set or change the properties of an existing formulation: 1. Right mouse click on the respective formulation in the **Building Blocks Explorer** 2. Select **Edit...** or simply double click on the formulation in the **Building Blocks Explorer** The window with the properties of the formulation will open. The properties can be set or changed appropriately. The changes are saved by closing the window by clicking on ![Image](/files/-LNl8Q5_I6QLMwPlc1Ju). ## Cloning Formulations To clone a formulation in the project: 1. Right mouse click on the respective formulation in the **Building Blocks Explorer** 2. Select **Clone...** 3. Set an alternative name for the formulation clone and enter a description, if desired. 4. Confirm and close the window by clicking **OK** . ## Formulations as Templates For each project, a number of formulations can be defined. They can be saved as a template and then be shared among several projects and users. To **save** an existing formulation as template: 1. Right mouse click on the respective formulation in the **Building Block Explorer** 2. Select **Save as Template...** In case a formulation with the same name already exists, a warning appears and you have the following opportunities: * Override: This action will override the existing template. * Save as: You can save the formulation under a different name. In this case, you will be asked to Rename the new template. * Cancel: This action will abort the saving process. To **load** an existing formulation from the template database: 1. Right mouse click on **Formulations** in the **Building Blocks Explorer** 2. Select **Load From Template...** 3. Select the desired formulation from the user templates In case a formulation with the same name already exists in the project, a warning appears and you will have to **Rename** the formulation that is to be loaded from template. 1. Click **OK** The selected formulation will appear in the **Building Blocks Explorer** view. In addition, formulations can be directly loaded from the template database within a simulation (see [Simulations](/working-with-pk-sim/pk-sim-documentation/pk-sim-simulations)). ## Deleting Formulations To delete a formulation from the project: 1. Right mouse click on the respective formulation in the **Building Blocks Explorer** 2. Select **Delete...** 3. Confirm to by clicking **Yes** {% hint style="warning" %} Please note that a formulation that is used in any simulation of the project cannot be deleted. {% endhint %} # Events In the building block **Event** you can define special events that are to occur during simulation time. These are, for example, the ingestion of a meal and the associated physiological changes, or the discrete emptying of the gallbladder independent of a meal event. {% hint style="info" %} Please note that the **Event** Building Block does not represent an essential building block for the simulation. {% endhint %} ## Definition of new Events in PK-Sim® To create a new event, do one of the following: * Click **Event** in the **Create** Group of the **Modeling** Tab, or * Right mouse click on **Events** in the **Building Blocks Explorer** and select **Add Event...**, or * Use the short cut **Ctrl+Alt+E** The following dialog will open in which the properties of the event can be selected and/or defined: ![Create Event dialog (with properties of a standard meal for humans)](/files/-LNl8S4pzSP8rwbGMiS6) First the event is initialized by giving it a **Name** in the respective input field. The name is used to identify the event when its parameters are saved in the project and/or as a template. The name is used for the identification of the event in the simulation. From the drop-down menu you can currently choose from the following predefined events: * Meal: Standard (Human) * Meal: High-fat breakfast (Human) * Meal: Ensure Plus® (Human) * Meal: High-fat soup (Human) * Meal: Mixed solid/liquid meal (Human) * Meal: Dextrose solution (Human) * Meal: Egg sandwich (Human) * Gallbladder emptying * Urinary bladder emptying ### Meals In the case of the meals, the typical composition of the selected meal is provided below the drop-down menu. The following model-relevant parameters of the meal are given: * Meal energy content in units of kcal or cal. * Meal volume in units of L or mL. * Meal fraction solid (value between 0 and 1), characterizing the composition of the meal with respect to solid and liquid components. Finally, the following two parameters can be defined: * The decision on whether the discrete gallbladder emptying should be enabled or disabled. Enabling gallbladder emptying will activate discrete mass flow from the gallbladder into the duodenum. * The gallbladder emptying lag time, i.e., the lag time between the ingestion of meal and gallbladder emptying {% hint style="info" %} Please note that enabling gallbladder emptying does not automatically imply active secretion of the compound into the bile! In order to simulate enterohepatic circulation of the compound, an active transport process from the liver into the bile is needed, i.e., the definition of an efflux transport process at the apical side of the hepatocytes or a biliary clearance process, which can be defined in the **Compound** Building Block, is required. {% endhint %} {% hint style="info" %} Please note that the rat lacks a gallbladder. The combination of discrete gallbladder emptying with the species rat, thus, is not possible! However, continuous bile flow from the hepatocytes into the duodenum can be simulated in the rat as well as in all other species. {% endhint %} {% hint style="warning" %} In order to additionally or alternatively activate continuous mass flow from the liver into the duodenum please change the parameter **EHC continuous fraction** in the **Individual** Building Block accordingly. In fasted humans, the fraction of hepatic bile that flows into the gallbladder averages about 60-70% and, accordingly, the fraction that flows directly into the duodenum is about 30-40%. Per default, however, the continuous bile flow is set to 0% as continuous enterohepatic circulation of a drug is frequently not observed, because this would only result in a net reduction of the plasma clearance. Other parameters related to the gallbladder emptying function, such as the gallbladder ejection fraction and the half-time of gallbladder emptying, can also be parameterized in the **Anatomy & Physiology** tab of the **Individual** Building Block. {% endhint %} For the various meals provided, the pH in the stomach and the gastric emptying rate will change significantly. Irrespective of the meal chosen, the gastric pH will be increased to 5.5 and then decay exponentially. The rate of gastric emptying, which controls the transport of the drug to the absorption sites in the intestine, will change according to a function that is based on the Weibull equation. The Weibull function was parameterized based on about 100 datasets for gastric emptying profiles in humans following ingestion of various meals \[[81](/references/references#81)]. {% hint style="warning" %} The predefined events are, so far, only parameterized based on information obtained for human adults. Therefore, the combination of these events with children and/or the various animal species in the simulation without adjusting certain meal parameters may not be possible. This is true particularly for the meal volume, which cannot exceed the volume of the stomach of the individual! {% endhint %} ## Setting or Changing Event Properties To set or change the properties of an existing event: 1. Right mouse click on the respective event in the **Building Blocks Explorer** 2. Select **Edit...** or simply double click on the existing event in the **Building Blocks Explorer** The window with the properties of the event will open. The properties can be set or changed appropriately. To save the changes close the window by clicking on ![Image](/files/-LNl8Q5_I6QLMwPlc1Ju). ## Cloning of Events To clone an event in the project: 1. Right mouse click on the respective event in the **Building Block Explorer** 2. Select **Clone...** 3. Set an alternative name for the event clone and enter a description if desired. 4. Confirm and close the window by clicking **OK** ## Saving Events as Templates For each project, a number of events can be defined. They can be saved as templates and then be shared among several projects and users. To save an existing event as template: 1. Right mouse click on the respective event in the **Building Block Explorer** 2. Select **Save as Template...** In case an event with the same name already exists, a warning appears and you have the following options: * Override: This action will override the existing template. * Save as: You can save the event under a different name. In this case, you will be asked to Rename the new template. * Cancel: This action will abort the saving process. To load an existing formulation from the template database: 1. Right mouse click on **Events** in the **Building Block Explorer** 2. Select **Load From Template...** 3. Select the desired event from the user templates In case an event with the same name already exists in the project, a warning appears and you will have to **Rename** the event that is to be loaded from template. 1. Click **OK** The selected event will appear in the **Building Block Explorer** view. Alternatively, events can be directly loaded from the template database within a simulation. ## Deleting Events To delete an event from the project: 1. Right mouse click on the respective event in the **Building Block Explorer** 2. Select **Delete...** 3. Confirm to delete the event by clicking **Yes** {% hint style="warning" %} Please note that an event that is used in any simulation of the project cannot be deleted. {% endhint %} # Simulations Simulations can easily be performed in PK-Sim® after having defined at least one building block for **Individuals**, **Compounds**, and **Administration Protocols** in the **Building Block** panel. Optionally, **Expression Profiles**, **Populations**, **Formulations**, **Events**, and **Observers** can be defined, and **Observed Data** loaded for the comparison with simulation results. Details on those building blocks can be found in the respective sections of this manual: * [PK-Sim® - Expression Profiles](/working-with-pk-sim/pk-sim-documentation/pk-sim-expression-profile) * [PK-Sim® - Creating Individuals](/working-with-pk-sim/pk-sim-documentation/pk-sim-creating-individuals) * [PK-Sim® - Creating Populations](/working-with-pk-sim/pk-sim-documentation/pk-sim-creating-populations) * [PK-Sim®- Compounds: Definition and Work Flows](/working-with-pk-sim/pk-sim-documentation/pk-sim-compounds-definition-and-work-flow) * [PK-Sim® - Formulations](/working-with-pk-sim/pk-sim-documentation/pk-sim-formulations) * [PK-Sim® - Administration Protocols](/working-with-pk-sim/pk-sim-documentation/pk-sim-administration-protocols) * [PK-Sim® - Events](/working-with-pk-sim/pk-sim-documentation/pk-sim-events) * [Shared Tools - Import and Edit of Observed Data](/shared-tools-and-example-workflows/import-edit-observed-data) Even if not all required building blocks are defined, you may still set up a simulation. You will then be systematically led through each missing building block where you can specify data or parameters. For details on each building block please refer to the respective chapters of this manual. Simulations are performed in 3 steps: Creating a simulation (see [Creating new simulations in PK-Sim®](#creating-new-simulations-in-pk-sim)), running a simulation (see [Running a simulation in an individual](#running-a-simulation-in-an-individual)), and displaying the results in the chart window (see [Analyzing results for a simulation in an individual](#analyzing-results-for-a-simulation-in-an-individual)). Experimental data can also be imported in the chart window to enable comparison to the simulated results and to facilitate model refinement. ## Creating new simulations in PK-Sim® To create a new simulation: * Click **Simulation** in the **Create** Group of the **Modeling** Tab, or * Use the short cut **Ctrl+Alt+S** In the **Create Simulation** dialog window the simulation is set up by specifying Individual or Population simulation, selecting the compound(s) from a list, and choosing the model settings: ![The Create Simulation dialog. Here, the Model tab is shown in which the Individual "European Male" has already been selected.](/files/-LNl8SE9TDEWiaBx2GHt) In order to create a new simulation, you are guided through the six tabs of the **Create Simulation** window: * The **Model Structure** tab to define model properties * The **Compounds** tab to select the compounds used for the simulation * The **Processes** tab to assign the relevant biological processes * The **Administration** tab to select between different predefined applications * The **Events** tab to choose a specific event defined in the **Event** Building Block * The **Observers** tab to select user-defined observers ### Definition of model structure In the **Model Structure** tab of the **Create Simulation** window you need to: * Enter a name for the simulation * Specify an individual or population by doing one of the following: * Select a previously defined individual or population from the drop-down menu * Define a new individual or population by clicking **Create** and follow the instructions of the dialog windows * Load a new individual or population from template by clicking **Load** and follow the instructions of the dialog windows * **Allow aging**: If a human individual or population is selected, the growth of the individual(s) during the simulation time will be taken into account when choosing this option. Based on the human growth and maturation functions available for most parameters in PK-Sim® (e.g., organ volumes, blood flow rates, organ composition, etc.), the parameters are updated along the time scale of the simulation. This is important for multiple drug administration to, e.g., preterm and term neonates, for which the rapid changes in anatomical and physiological properties can influence the pharmacokinetics during the simulated study. Please note that the use of the growth function will need additional simulation time so that it is recommended to use this option only if really needed. * Specify compound(s) by doing one of the following: * Select a compound from the list of previously created compounds in the Building Block window. * Create a new compound by clicking **Create** and follow the instructions in the dialog windows. * Load a new compound from template by clicking **Load** and follow the instructions in the dialog windows. * Select the model settings, i.e., either select the standard model for small molecules, or the model for proteins and large molecules #### Model settings | Model Settings | Description | | -------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Standard model for small molecules |

The PK-Sim® standard distribution model assumes 4 subcompartments per organ, i.e. compartments for blood cells, plasma, interstitial space, and cellular space. This model type considers a permeation barrier between plasma and interstitial space and takes into account that the interstitial space has a lower protein content than the plasma. It is especially suitable for small molecules.
The plasma-interstitial partition coefficients result from the lower protein concentration in the interstitial space compared to plasma and the unbound fraction in plasma. It is assumed, that the drug has the same affinity to plasma as to interstitial proteins. Thus, effects from the partitioning between plasma and interstitial space may (depending on other physico- chemical data) become important for compounds with a low fraction unbound.
The rate of permeation through the endothelial barrier between plasma and interstitial space is determined by the product of endothelial permeability and surface area. The drug dependent permeability can be defined within the Distribution Tab and the individual dependent surface area can be defined for the individual. In the present version of PK-Sim®, the endothelial permeability parameters of the plasma-interstitial barriers are not calculated from physico-chemical compound data. The default value for the plasma-interstitial permeabilities is very large, i.e. the permeabilities have to be adjusted manually, if the permeation across the plasma-interstitial barriers of the organs is expected to be restricted. Using the large default value for plasma-interstitial permeabilities, the exchange rate between plasma and interstitial in 4 subcompartments model are almost instantaneous.

| | Model for proteins and large molecules | This model type was developed to simulate the pharmacokinetics of macromolecules such as therapeutic proteins. It is an extension of the standard model for small molecules and contains a description of the transcapillary drug exchange, lymph flows and an additional sub-compartment per organ that represents the endosomal space. The endosomal compartment contains FcRn receptors that are able to protect the macromolecules from catabolism via binding to these receptors (important for e.g. IgG antibodies). | {% hint style="info" %} Please note that currently only for mouse, monkey and human species specific values for the concentration of the FcRn receptor, the concentration of the endogenous IgG and the affinity of the endogenous IgG to the FcRn receptor (needed for the **Model for proteins and large molecules**) are available. In case of all other animal species just reasonable values are used as physiological default values. {% endhint %} ### Review compound settings In the **Compounds** tab of the **Create Simulation** window you can review the *Calculation methods* selected for the partition coefficients and the cellular permeabilities. Also, you can review and override values for the *Parameter Alternatives*. ![The Create Simulation dialog. Here, the two selected compounds can be viewed in the tabbed view.](/files/-LOWQ590JKm7eD3NpN3A) Click **Next** in order to assign the relevant biological processes. Note that you can switch between the **Tabbed view** and the **Accordion View** in the **Utilities/ Options** menu if you selected more than one compound. ### Select relevant biological processes ![The Create Simulation dialog. Here, the Processes tab is shown, in which the proteins, i.e. the enzymes, transporters and binding proteins, expressed in the Individual can be linked to the corresponding active processes defined in the Compound.](/files/-LNl8SEK70ugG3OShirH) In the **Processes** tab of the **Create Simulation** window, processes like metabolic, transport, excretion and specific binding processes defined in the selected individual (or population) can be linked to the ADME properties of the selected compounds. A detailed description of how to set up an interaction of a drug with enzymes/transporters (e.g., a drug-drug interaction or induction) can be found in [PK-Sim® Compounds: Defining Inhibition/Induction Processes](/working-with-pk-sim/pk-sim-documentation/pk-sim-compounds-defining-inhibition-induction-processes). {% hint style="warning" %} If, and only if, processes in individuals are linked to the properties of the compounds, these processes are considered in the simulation. {% endhint %} {% hint style="info" %} A green check mark indicates that the process is modeled when running the simulation whereas the yellow exclamation mark indicates that there is no match between the expression data defined in the individual and active processes defined in the compounds, as shown in the following screenshot. {% endhint %} Example 1: ![Example 1: Overview](/files/-LNl8SEMbbRN4dRrrL9X) Example 2: Renal excretion of the compounds should be incorporated into the model. The following settings are required for the selected individual (the capability of renal excretion is a default setting): ![The Create Individual dialog. Here a european male will be created.](/files/-LNl8SEOnr187DLJPlgK) Add a renal clearance process for the selected compound in Compound → Biological processes → Transport & Excretion → Renal clearances, as exemplified in the following screenshot: ![Defining the renal clearance process.](/files/-LNl8SEQ2884vBeP0D56) Link the process in the individual with the biological process of the compound (if not yet automatically done): ![The Transport & Excretion dialog. Here paper 2 is assigned as data source for renal clearances.](/files/-LNl8SESyov_ierF5M05) Click on **Next** in order to define the administration protocol. ### Select administration In the **Administration** tab of the **Create Simulation** window, the administration protocol can be loaded from the project database or from a template. Further, a novel administration protocol can be defined and used. In addition, in the case of oral and user defined administration types, a formulation is required for the simulation. ![The Create Simulation dialog. Here, the Administration tab is shown, in which different administration protocols can be selected for different drugs. At least one compound must be administered.](/files/-LOWQ59L9Ah0kc4dx6kR) To insert an administration do one of the following: * Select a previously defined protocol from the **Administration Protocol** drop- down menu * Define a new administration by clicking **Create** and follow the instructions of the dialog windows * Load an administration from the template database by clicking **Load** and follow the instructions of the dialog windows In case of oral and user defined administration, you will have to additionally map the formulation(s) defined in the **Formulation** building block. In case of sophisticated dosing schedules, different formulations can be chosen for the various administration times. For an intravenous administration (Intravenous Bolus and Intravenous Infusion), the definition of a formulation is not necessary, because the drug is always assumed to be given in solution. For further information please see [PK-Sim® - Administration Protocols](/working-with-pk-sim/pk-sim-documentation/pk-sim-administration-protocols). {% hint style="info" %} None or exactly one administration protocol can be assigned to every compound used in the simulation. Each administration protocol can be assigned to maximally one compound. {% endhint %} ### Select events (optional) In the **Events** tab of the **Create Simulation** window, events such as the administration of meals and/or discrete gallbladder emptying can be defined at various points of the simulation. ![The Create Simulation dialog. Here, the Events tab is shown, in which the administration of a Standard Meal immediately at the start of the simulation is selected.](/files/-LNl8SEWkjsMvktklmX4) Events are optional for creating a simulation. Possible predefined events are currently the application of a meal to simulate fed conditions for an oral administration, gallbladder emptying independent from meal administration, and urinary bladder emptying. To insert an event do one of the following: * Select a previously defined event from the **Event** drop-down menu * Define a new event by clicking **Create** and follow the instructions of the appearing dialog windows * Load an event from the template database by clicking and follow the instructions of the appearing dialog windows Click **OK** to finish the **Create Simulation** process and to close the window. If you have successfully created a simulation, it will appear in the simulation window with its name and its components: ![The Simulations explorer.](/files/-LNl8SEaHf7eJteaLULR) {% hint style="info" %} The green check marks indicate that the building blocks used in the simulation have the same settings as the original building blocks saved in the building blocks explorer window. Changing the settings in the simulation is done locally without affecting the original building blocks in the building block explorer window. {% endhint %} ## How to set up a parent/metabolite simulation PK-Sim® offers two alternatives to define drug metabolites. First, metabolites can be a "sink" which means that not actively or passively transported. They possess no physico-chemical or ADME properties and cannot be used as compounds in a simulation. Second, one of the compounds in a simulation can be assigned to be a metabolite or another compound. The metabolite possesses physico-chemical and ADME properties and be transported. In addition, the metabolite can be used in further metabolizations and thus a metabolic network can be built. ![The name of the metabolite can be defined in specifying the metabolic processes.](/files/-LNl8SEcjPj6ZiqIa170) If you want the compound not be treated as sink, it needs to be included into the list of compounds in the building blocks. ![Metabolites are treated like any other compounds when listed in the building blocks.](/files/-LNl8SEeUo_Q-53rU3TV) If you click on **Show Diagram**, a reaction network of all reactions in the simulation is shown (not just the metabolic network). ![All reactions in a simulation are depicted in the reaction diagram.](/files/-LNl8SEgXsTdimXa7YuK) ## Mapping Outputs to Observed Data In the **Observed Data** tab observed data sets can be mapped to the corresponding simulation outputs. This mapping is required e.g. for displaying goodness of fit plots and is used as **default** when adding the simulation to a parameter identification. All observed data sets belonging to the opened simulation are listed in the mapping table. When adding or removing an observed data set to/from the simulation, the table is updated. Newly added observed data sets are automatically mapped to simulation outputs according to `Organ`, `Compartment` and `Molecule` meta data of the data set and path elements of the outputs. If no matching output can be found, the mapped simulation output is set to **None**. This means that the specified observed data set is not mapped. The user can also clear an output mapping by selecting the **None** entry from the Output dropdown. By clicking the **"x"** on the right side of the grid, the user can delete the observed data from the simulation. ![In the Observed Data Tab observed data can be mapped to simulation outputs.](/files/D8Dl0YEKN2VnxPVb0OW8) {% hint style="warning" %} Because meta data of observed data can be incomplete or wrong, you should check whether the right output is mapped to each observed data set. In case of different outputs with the same meta data (this can happen at least in MoBi), you should also check whether the automatically chosen output is correct. {% endhint %} {% hint style="info" %} In case of incomplete or missing meta data, it is recommended to correct the meta data first to enable automatic mapping. {% endhint %} For each mapping, the scaling can be defined as **Linear** or **Log** which determines the residual calculation. **Scaling** | | | | ---------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Linear** | Residuals are calculated as: `Simulation value - Observed value`. This means that the residuals are defined by absolute differences. If the magnitudes of values are different for different parameters, the different magnitudes of residuals should be harmonized by corresponding weights (reciprocal values). | | **Log** | Residuals are calculated as: `log(Simulation value) - log(Observed value)` = `log (Simulation Value / Observed Value)`. This means that the ratio of values is considered which is independent of the magnitude of the value. | To reflect the quality or importance of the Observed Data set you can edit the weights of each mapping. ### Handling of missing values for residuals If there is no simulated time value corresponding to an observed time value, linear interpolation between simulated points is used to calculate the missing simulated value. This happens in the calculation of the Residuals in the Simulation, opposed to the calculation of Residuals in Parameter Identification (where every observed time point is added to simulation output points). This might result in slightly different total error values calculated in "Simulation" view and in Parameter Identification. ## Running a simulation in an individual If a simulation was successfully created, press the **Run** simulation button in the **Run & Analyze** ribbon or press the F5 key. If the simulation is run for the first time, the following window will appear in which the simulation curves that will be generated in the simulation can be selected: ![The Individual Simulation Settings window. Here, the organs and compartments for which concentration time curves are generated in the individual simulation can be selected.](/files/-LNl8SEki5cb23g2FPVT) Per default, the Peripheral Venous Blood Plasma is pre-selected. If desired, select further outputs and then press **OK**. The result of the individual simulation will be automatically displayed. In order to select another or additional outputs for the current simulation, click on **Define Settings and Run** simulation button. {% hint style="info" %} By clicking **Save Settings into...** at the bottom left corner of the **Curve Selection window** the settings can be saved as a default for the project or as a user-specific default. {% endhint %} Two venous blood outputs can be selected: “Venous Blood” and “Peripheral Venous Blood”. “Venous Blood” refers to the compartment “Venous Blood” representing the large veins. In clinical practice it is common to sample blood at patients superficial veins, e.g. the antecubital vein. Therefore, PK-Sim® offers the opportunity to also display the pharmacokinetics of the drug in the peripheral venous plasma in order to allow a more accurate description of clinical data. Per default “Peripheral Venous Blood” is a weighted mean of skin and muscle tissue blood (about 70% contribution from skin and about 30% contribution from muscle for all species). You can change the default contribution to “Peripheral Venous Blood” by adjusting the parameters “Fraction of peripheral blood flow in organ” at “Physiology” -> “Flow Rates” -> “Peripheral Blood Flow Fraction” (select “Advanced” view for parameters). The contributions can be defined for arterial blood, bone, fat, muscle, and skin, i.e. all compartments which could possibly contribute to “Peripheral Venous Blood”. The arterial plasma is also considered because of the arteriovenous anastomoses in e.g. the skin of the hand (shunts between arteries and veins involved in the regulation of body temperature). A similar approach to describe peripheral venous plasma concentrations can be found in literature \[[41](/references/references#41)]. {% hint style="warning" %} As the observer for peripheral venous blood sampling represents a balanced mixture of plasma concentrations of the drug in arterial blood, bone, fat, muscle, and skin, please do not use the peripheral venous blood observer in the case of, e.g., subcutaneous or intramuscular drug administration. This will lead to an overestimation of the concentration in plasma. {% endhint %} ![The Results tab of the Simulation window. Here, the simulated plasma concentration-time profile following oral administration of a diclofenac IR tablet is shown in comparison to experimental data.](/files/-LOWQ59oZsHVTWH-gQw3) For general information about the chart component, i.e., chart settings and options etc., please see [Chart Component](/shared-tools-and-example-workflows/chart-component). {% hint style="info" %} If you would like to cancel the running process, press the **Stop** button next to the **Run** button. {% endhint %} If you wish to change the settings of the simulation, click on the **Parameters** tab. If you have simulated a population, there are two more tabs **User Defined Variability** and **Distribution** in which the settings also might be changed. For both, individual and population simulations, there are three views on the parameter settings to select at the bottom of the window: ![The Parameters tab of the Simulation window. Here, the Settings of the simulation are shown.](/files/-LNl8SEoNQRn0ywKNolS) * **Simple view**: in this view, not all parameters are displayed * **Advanced view**: all parameters are displayed * **Hierarchy view**: all parameters are displayed as located in the spatial model structure You may change the parameter settings for your simulation in order to, e.g., achieve a better fit to the observed data. The settings in the building blocks will be unaffected. {% hint style="info" %} It is recommended to select all parameters under consideration as **Favorites** and to document the source of all parameter values changed from the default in the column **Value Description**. Then you have a comprehensive overview about the essential input of your simulation, which you can document by copying just the Favorites table. {% endhint %} {% hint style="info" %} **User Defined** parameter node shows an overview of all parameters changed by the user in the simulation. ![User defined parameters.](/files/-LQ9BVipl3vKMr3ZoMJ0) {% endhint %} {% hint style="warning" %} If you change the parameter settings in the **Parameter** tab, the green check marks (traffic lights) on the Results tab will turn red indicating that the displayed simulation results were not performed with the current settings: ![Image](/files/-LNl8SEqNdEZQOJagQxu)\ Press the **Run** simulation button in the **Modeling & Simulation** ribbon or press the **F5** key again to re-run the simulation with the current settings and display the results. {% endhint %} ## Synchronization options for building blocks in a simulation If parameter settings were changed in the simulation, the red traffic lights in the **Simulation** window indicate that the **local settings** in the simulation are different from the settings in the **Building Block**, i.e. the **global settings**: ![Image](/files/-LNl8SEsIUDwV41p1jO2) A right click on the red traffic lights in the simulation window allows for two possibilities: ![Image](/files/-LNl8SEuW44ErUBnt8oa) You can synchronize the settings between the building block and the simulation through the context menu of the affected building block in the simulation: * **Update from building block**: The simulation settings (local) will be updated with the (global) settings of the building block. This is useful if you want to discard the settings of your simulation and get back to the original settings defined in the building block. * **Commit to building block**: The (local) settings of the simulation will be committed to the building block (global settings). This is useful if you want to make these settings available in other simulations. * **Configure**: Instead of updating a single building block within your simulation you can also Configure the entire simulation and update or exchange several building blocks at a time. To do so, right mouse click on the simulation and select Configure. The Create Simulation dialog will open where you can exchange the parameters and building blocks of your simulation. In the case of building blocks for which changes were made in the simulation, the name will be supplemented by the warning This is not the template building block!. To update the settings of the simulation select the appropriate building block from the drop-down menu. ## Analyzing results for a simulation in an individual As described in the previous chapter **Run simulation**, clicking on **Run** in the **Modeling & Simulation** ribbon or pressing **F5** starts the calculation of the simulation. The results will be automatically displayed after finishing the calculation. The calculated results can the be exported to various file formats. {% hint style="info" %} For more information on displaying and editing the charts, see [Chart Component](/shared-tools-and-example-workflows/chart-component) For more information on uploading observed data, see [Import and Edit of Observed Data](/shared-tools-and-example-workflows/import-edit-observed-data) {% endhint %} Generally, two different views are available and switching between these view can be done by clicking on **Show PK-Analysis** and **Show Chart** button on the bottom of the chart window: * Chart view (default): The simulated curves and the observed data are displayed * PK-Analysis view : The calculated PK parameters for the selected simulated curves are displayed. ### Chart view The simulated curves can be displayed. If simulated curves selected in the curve selection window are missing after (re-)running a simulation, most probably these are not selected in the chart. The graphs can be selected by clicking on **Chart Editor** on the right hand side of the chart. Curve options, axis options and chart options can be selected here and the general layout of the chart can be configured. {% hint style="info" %} For more information on displaying and editing the chart Display, go to [Chart Component](/shared-tools-and-example-workflows/chart-component) {% endhint %} For comparison, observed data in MS Excel® format (\*.xls and \*.xlsx) can be loaded and displayed in the chart as well. If observed data were added to the **Observed Data** Building Block, they can be added to the chart by dragging and dropping them onto the chart. {% hint style="info" %} For more information on how to load observed data and compare them to your simulated data, go to [Import and Edit of Observed Data](/shared-tools-and-example-workflows/import-edit-observed-data) {% endhint %} #### Multiple results windows If you wish to display different curves or use different settings for the same simulation, you can add new results charts windows by clicking on the **Results** button in the Ribbon group **Simulation**. #### Special features for population simulations If you wish to display other percentiles or other curves without simulating again, click on the **Results** button in the ribbon group **Simulation**. You will be directed to the **Curve selection for chart** window (see above). ### PK-Analysis view If a simulation has been successfully created, click **Show PK-Analysis** on the bottom of the chart window. PK parameters are then calculated and displayed next to the chart. ![PK-Analysis view of the Results window.](/files/-LOWQ5AI-r7-sKUIoPqE) #### PK-Parameters The calculated pharmacokinetic parameters are: 1. In all simulations: | PK parameter | Description | | ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | AUC\_tEnd |

Area under curve from tstart to tend of the simulation.
Image

| | AUC\_inf |

Area under curve extrapolated to infinity (using the terminal 10% of data points).
Image
, where λ is the terminal elimination rate (calculated from the terminal 10% of simulated points).

| | %AUC(tlast-inf) |

Percentage of AUCinf after end of simulation time.
Image

| | AUC\_tEnd\_norm |

Area under curve extrapolated to infinity and normalized to the dose dose in drug mass per body weight.
Image

| | AUC\_inf\_norm |

Area under curve extrapolated to infinity and normalized to the dose \[dose in drug mass per body weight].
Image

| | AUC Ratio (AUCR) | AUC\_I/AUC (Area under the plasma concentration-time curve of the substrate in the presence of the inhibitor / Area under the plasma concentration-time curve of the substrate in the absence of the inhibitor) | | C\_max | Maximum concentration | | C\_max\_norm | Maximum concentration normalized to dose dose in drug mass per body weight | | C\_max Ratio (Cmax\_R) | C\_max\_I/C\_max (Maximum concentration of the plasma concentration-time curve of the substrate in the presence of the inhibitor / Maximum concentration of the plasma concentration-time curve of the substrate in the absence of the inhibitor) | | C\_tEnd | concentration at the end of simulation | | t\_max | Time at which the maximum concentration is assumed | | Half-Life |

Terminal half life time (calculated from the terminal 10% of data points).
Image
, where λ is the terminal elimination rate (calculated from the terminal 10% of simulated points).

| | MRT |

Mean residence time is calculated by:
Image
The infusion time is set to 0 for non intravenous administrations. The AUMCs are calculated according to:
Image
Image
, where λ is the terminal elimination rate (calculated from the terminal 10% of simulated points).

| * In simulations with intravenous administration: | PK parameter | Description | | ------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | VSS(plasma) |

Volume of distribution at steady state calculated from the plasma curve according to:
Image

| | Vd(plasma) | Apparent volume of distribution is calculated from the plasma curve according to: ![Image](/files/-LOWQ5AhSrbonq9PyX_b) , where `λ` is the terminal elimination rate (calculated from the terminal 10% of simulated points). If simulation time is short, the distribution volume may be incorrect. Run a longer simulation (to approach steady state) and reevaluate the distribution volume. | | Vss(phys-chem) | Predicted volume of distribution = Volume-weighted mean organ to plasma partition coefficient calculated from physico- chemical compound data. | | Total plasma clearance CL |

Total clearance calculated from plasma curve according to:
Image

| | Total body clearance | D/AUC - Total body clearance of drug or apparent clearance (CL/F for extravascular application), dimension is ml/min/kg | * In simulations with oral administration | PK parameter | Description | | ------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Vss(plasma)/F | Volume of distribution at steady state calculated from plasma curve (see above) divided by bioavailability | | Vd(plasma)/F |

Apparent volume of distribution calculated from the plasma curve according to
Image
(see above) divided by bioavailability

| | Total plasma clearance/F |

Total clearance calculated from plasma curve according to
Image
divided by bioavailability

| | Fraction absorbed | Absorbed fraction of applied oral dose. Please note that, e.g. in the case of enterohepatic circulation, this fraction may exceed 1 | | Bioavailability | The bioavailability is only calculated on request. After pressing the button **Bioavailability** a second simulation with an intravenous (i.v.) short infusion is carried out (internally without being displayed) using identical parameters to the last simulation with oral (p.o.) administration. The bioavailability is then calculated from AUCinf (p.o.)/AUCinf (i.v.) in the venous blood compartment. For a proper estimate of the AUCinf (p.o.) it is recommended to simulate as long as total gastrointestinal transit takes. After changing any parameter the results of previously run simulations are no longer valid. In such a situation, the **Bioavailability** button is deactivated until the p.o. simulation has been executed with the current parameters. | * In simulations with multiple administrations | PK parameter | Description | | -------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | AUC\_inf\_tD1 | Area under the concentration vs. time curve from the first data point extrapolated to infinity (further administrations are not considered!) | | AUC\_inf\_tD1\_n | oArmrea under the concentration vs. time curve from the first data point extrapolated to infinity (further administrations are not considered!) normalized to dose, with dose in drug mass per body weight | | ....tDi-tDj | Respective PK parameter from the administration time of the first dose until the administration time of the second dose | | ....tDlast-tDEnd | Respective PK parameter following the last application | | ....tDlast-1- tDlast | Respective PK parameter in the interval between the (last -1) application and the last application | | C\_trough\_dDi | Trough concentration just before the i-th dose is administered | | C\_trough\_dlast | Trough concentration just before the last dose is administered | All values are calculated using the standard equations for PK-values (see e.g. M. Rowland, T. N. Tozer, “Clinical Pharmacokinetic Concepts and Applications”, (1994) Lippincott Williams & Wilkins, Philadelphia). For extrapolation to infinity an exponential function is used on the basis of the last 10% of the calculated time steps. AUC is calculated by extrapolating the first time steps to t = 0. Depending on the curve shape the result of this extrapolation may be sensitive to time resolution. This may lead to some variability in AUC and thus, in clearance and distribution volumes. PK-parameters for selected outputs of population simulations are shown in two ways: 1. Individual PK Values are calculated for all individuals within the range being analyzed and the median is presented 2. Aggregated PK Values are calculated from aggregated curve being analyzed Globally calculated PK-parameters are always calculated for all individuals with the median being presented By clicking on **Export to Excel**® the calculated PK-parameters (including the simulated concentration-time profiles) can be exported to MS Excel® format. ## Running and analyzing a population simulation ### The population simulation analysis Population simulation analysis function offers a variety of analyses and graphical displays: Time Profile, Box Whisker, Scatter and Range Analysis that will be explained in detail in the following sections of the manual. ### Running a population simulation Unlike for simulations in single individuals, additional variability for parameters in population simulations may be defined. In the **User Defined Variability** tab, parameters from all building blocks that need to be varied may be selected and specific distributions/variabilities can be set. In the **Distribution** tab, these settings are graphically visualized. {% hint style="info" %} For more information on adding variability to a defined population, go to [PK-Sim® - Creating Populations](/working-with-pk-sim/pk-sim-documentation/pk-sim-creating-populations). {% endhint %} Once all parameters are set, click the **Run** simulation button in the **Modeling & Simulation** group or press the **F5** key. The **Population Simulation Settings window: Curve selection** window will appear in which organs and compartments are selected in which time profiles and PK-parameters will be calculated. ![The Population Simulation Settings: Curve Selection window. Time profiles and PK-parameters will be calculated in the selected organs and compartments.](/files/-LOWQ5Avki1iWvbZGQx9) Choose the organ and the compartment by expanding the respective drop-down menue and select by ticking the box in the right column of the table. Press **OK** to start the simulation run. By clicking into the **Save Settings** at the bottom left corner of the **Curve Selection window** the settings can be saved as user-specific default. ### Analyzing a population simulation After the simulation has been calculated, the **Create Time Profile Analysis** window opens up next in which the graphical display of simulated time profiles can be specified. If you do not want to plot time profiles, close this window and choose the analysis type you require from the **Analysis** button. For plotting time profiles, use the **Output** tab to specify in which of the previously selected organs/compartment you want to analyze and plot time profiles. Highlight the respective organ/compartment and add it to the right panel. In the panel below, the **Outputs: Select distribution statistics for display**, you may specify which statistical quantity of your output will be graphically displayed. {% hint style="info" %} You may change the name, the unit and the scaling of selected output in all plot types. Changing the name may be useful when graphically displaying several parameters and the parameter name is printed along the y-axis. {% endhint %} {% hint style="info" %} The calculated PK-parameters of all individual curves can be exported using the **Export PK-Analyses to CSV...** item from the context menu of the simulation. {% endhint %} {% hint style="info" %} The underlying data of population analysis can be exported to Excel® using the **Export to Excel**®\*\*...\*\* item from the context menu of the chart view. Two sheets are created containing the data as original and transposed matrix. {% endhint %} ![Select specific curves from the list of organs/compartments in which time profiles were simulated.](/files/-LNl8SFbzxuD_Gb1fhqZ) #### Definition of groupings Output may be grouped using population parameters and PK-parameters. The **Population Parameters** tab offers grouping by population parameters e.g. Characteristics of individual (weight, age, etc.), anatomy or physiology. A comprehensive list itemizes each PK-parameter in the organs/compartments specified in the **Outputs** tab. In order to select a parameter as a grouping criterion, expand the tree underlying each group of criteria and use the **Add** or **Remove**button to add or remove a specific grouping PK-Parameter to the right panel. Highlight the respective grouping and click on the **Create Grouping** button to specify the grouping intervals (binning). For PK-parameters with numerical values like C\_max or AUC grouping can be done into equally sized intervals using the **User defined limits**. Alternatively, grouping by numerical PK-parameters can be done into equally populated intervals of varying size using the **User defined (equally populated) number of bins**. For PK-parameters that assume string values like gender or race grouping is defined by **Value mapping**. Groupings have to be named and the name of the grouping appears later on as an item in the list of grouping parameters. **User defined limits** Grouping by customized intervals is available in both the **Population Parameter** and the **PK-Parameter** tabs. If you decide on defining the limits of each bin, the minimum and maximum values of your grouping criterion are automatically entered in the table listing the grouping intervals. Continue as follows: * Define the maximum value of the first bin. * Add additional bins by clicking on the **+** button in the right column of the table that lists the binning intervals. * In your last bin, the upper limit of you last bin is the maximum value of the parameter. * For each interval, select a label and change color and symbol (used in scatter plots) by changing default settings. ![Using customized grouping of output by Population Parameters or PK- Parameters.](/files/-LOWQ5B13mKNOoE5eQuH) **User defined (equally populated) number of bins** If you decide on using equally populated bins for grouping of your output, labels for the individual bins have to be designed for the display. In the **Label Generation** panel, do the following: * Decide on the number of bins used for grouping. * Choose from the drop-down menu a symbol that will be used in a scatter plot. * Choose a start and end color for plotting the output in the first and the last interval. The color gradient in between is set automatically. Colors in individual intervals can be changed in the **Generated Label** panel below. * Individual intervals are named using the selected **Naming pattern** that can be customized. Per default it consists of the selected **Template** e.g. alphabetic or numerical labelling together with the lower and upper limit of the interval. However, any of these elements may be omitted. More information on customizing the label generation are available directly within the software. {% hint style="info" %} When you finish defining the grouping intervals, the grouping appears in the list of selected parameters. If you highlight a specific grouping, the lower panel of the **Population Parameters** and the **PK-Parameters** shows the distribution of the individuals of the population when stratified by this grouping along with the label of each bin. {% endhint %} **Value mapping for string parameters** Population parameters such as gender, race and population name can be grouped by their string values. This grouping can be used to customize labels e.g. F or M instead of Female or Male and/or the relative order of these labels in the analysis (i.e. which label should come first) menu serves the design of customized labels. #### The Time Profile Analysis In the **Time Profile** tab, concentration-time profiles or fraction-time profiles can be plotted. First, in the **Selected Outputs** window, select from list of previously specified organs/compartments the concentration-/fraction-time profile(s) that you want to plot. Please note that concentration and fraction cannot be used at the same time for a given analysis. Second, if you want to display by grouping, select from the **Available Fields** panel a grouping criterion specified in the **Population Parameters** or the **PK-Parameters**. There are several ways to visualize stratified results: * If you drag a grouping criterion into the **Panes** panel, time-profiles in each subgroup will be displayed in a separate panel on the right. More than one grouping criterion may be selected and the respective number of panels will be generated. * If you drag a grouping criterion into the **Colors** panel, time-profiles in each subgroup will be displayed in one color. Colors were previously selected in the **Outputs** window. Only one grouping criterion may be selected here, to be able to differentiate the subgroups. * If you want to display results grouped by two criteria, use the **Panes** and the **Colors** panels simultaneously. In this case, it may wise to select only one output because curves from different compartments can only be differentiated by their progression. For each curve PK parameters are calculated and can be shown by clicking on the **Show PK-Analysis** button. * Chart view (default): The calculated curves and the observed data are displayed * PK-Analysis view : The calculated PK parameters for the selected calculated curves are displayed. See “PK- Analysis view”. ![Display simulated concentration-/fraction-time profiles stratified by Population Parameters and/or PK-parameters.](/files/-LNl8SFjbACa8CCxe1ie) If you hover over the simulated time-profiles, details of the curve are displayed, e.g. the organ/compartment in which the time-profile was simulated, the statistical quantity that is plotted and the x- and y-values of the underlying data points. Details of your grouping can be changed: * Go back to the **Population Parameters** or the **PK-Parameters** tab. * Highlight the name of the grouping in the panel listing the selected parameters. * Right mouse click on the name of the grouping and select **Edit** from the menu. * Confirm and close the window by clicking **OK** {% hint style="info" %} Use the magnifying glass to zoom into an area that you wish to enlarge. {% endhint %} {% hint style="info" %} Use the magnifying glass to zoom into an area that you wish to enlarge. {% endhint %} #### Displaying Observed Data in the Time Profile Analysis In order to display **Observed Data** in your Time Profile Analysis do and note the following: * Drag and drop the observed data from the Building Block panel into the Analysis panel. * Either display specific files or folders of observed data in the building block. * Use the **Chart Options** to specify the settings for display of the observed data. * When observed data is displayed for the first time, it appears in all analysis panels by default. * In the Chart Options, observed data can be grouped by meta data and is displayed in the respective panel. To apply the grouping also to the observed data the meta data field of the observed data must be named like the field in the analysis and the value must match. * Once observed data is dragged into the analysis panel, it is associated to that simulation and can be removed by removing the observed data from the simulation tree. {% hint style="info" %} For comparison charts observed data can not be removed from the analysis, but only made invisible by unticking the **Visible** box in the Chart Options. {% endhint %} ![Display observed data in a time profile analysis. Upon drag and drop into the analysis, observed data is displayed in all panels by default.](/files/-LOWQ5BEb-9y-5Q-WR7c) ![Observed data can be grouped by meta data used in stratification and is then displayed in the corresponding panel only.](/files/-LOWQ5BH8C_HHJVmWK7-) #### The Box Whisker Analysis In contrast to the Time Profile Analysis, population parameters and PK- parameters serve not only as grouping criteria in the Box Whisker Analysis, but may also be plotted. Any parameter selected in the **Population Parameters** tab and **PK-Parameters** tab is listed in the **Selected Outputs** panel of the **Box Whisker Plot** tab. Select a parameter for plotting by ticking the respective box. Grouping criteria are defined as described above and can be selected from the **Available Fields**. For grouping along the x-axis, several criteria may be selected by dragging to the **X-Grouping** panel. Grouping by color may be used for one criterion only and a corresponding legend is automatically created. The box comprises 25% (lower rim) to 75% (upper rim) of the values. The whiskers extend from 2.5% to 97.5% of the values in the population. The distance between the lower and upper box rim is called the inner quartile range (IQR). Outliers are values which lie outside the range from lower whisker limit - 1.5 time IQR to upper whisker limit + 1.5 time IQR. ![Display simulated parameters in a box whisker plot stratified by Population Parameters and/or PK-parameters.](/files/-LOWQ5BKfutB1adTATYO) A separate panel is created for each of the selected output parameters in the graphical display. The name and unit of the output parameters is printed along the Y-axis. #### Predicted vs. Observed For each observed value a point is plotted with observed value as x-Value and corresponding simulated value as y-Value. ![Simulation Predicted vs Observed Chart.](/files/Ud5rMfHU55rc9hEXzXUW) **Adding Deviation Lines to the plot** In a *Predicted vs. Observed* plot the user can right click on the chart and add deviation lines: ![Add Deviation Lines Context Menu Entry](/files/H4NpCLb5hr7ZxUE3llLB) This opens a dialog where the user can specify the fold value of the deviation curves. ![Deviation Line Dialog for specifying the fold value](/files/meOKvckPZLj9TnXvEj7r) This will create two deviation lines according to the given x-fold value which has to be greater than 1. An x-fold deviation range includes simulated values within x-fold and 1/x-fold of observed values. ![2-fold Deviation Lines](/files/vfLwhn7oGZJyUiQPlZqp) In the Chart Editor the deviation lines are grouped under the Category Identity. #### Residuals vs. Time This chart is similar to the Time Profile chart, but on the y-axis the (absolute) residuals are plotted. The chart includes scaling and weights. ![Simulation Residuals vs Time Chart.](/files/x8aHDShxtkK4sjL2l05d) At the top of the chart, the **total residual error** is displayed. #### The Scatter Plot Analysis In the **Scatter Plot Analysis** population parameters and PK-parameters can also be used as grouping criteria and be plotted. Grouping criteria are defined as described above. In addition to grouping in different panes or by different colors, you can group your output by symbols. Do so by dragging a grouping criterion into the **Symbols** panel. The symbols need to be defined along with the other grouping criteria in the **Population Parameter** or **PK-Parameter** tab. ![Display simulated parameters in a scatter plot stratified by Population parameters and/or PK-parameters.](/files/-LOWQ5BNX_LLI5qwVFut) #### The Range Plot Analysis Similar to the **Scatter Plot Analysis**, the **Range Plot Analysis** offers continuous plotting of parameters on both axis. Grouping by **Population Parameters** and/or **PK-Parameters** is done as described above. The range plot displays the median of the parameter as a thick line and the parameter range that comprises 5-95% of individuals of the population. ![Display simulated parameters in a range plot that displays the median and parameter range covered by 5-95% of individuals of that population.](/files/-LOWQ5BQG0ZR4B3mYwx6) Details of your analysis can be changed by right mouse click into the plot and selecting **Edit**. ### Cloning a Simulation In certain cases, it can be helpful to clone a simulation, e.g. in order to keep all parameters defined in the simulation, such as the partition coefficient method, and exchange only one particular building block, e.g. the administration protocol. This can easily be done by cloning an existing simulation and subsequently exchanging the respective building block using the **Configure** functionality (see above). To clone a simulation in the project: 1. Right mouse click on the respective simulation in the Simulations Explorer 2. Select **Clone...** 3. The **Cloning Simulation dialog**, which is identical to the **Create Simulation dialog** for new simulations, will open. You will have to enter an alternative name for the simulation clone. 4. You can now go through the **Cloning Simulation dialog** and exchange parameters and/or entire building blocks of your simulation clone. To update the settings of the simulation select the appropriate building block from the drop-down menus. 5. Once all parameters and building blocks are appropriate confirm and close the window by clicking **OK** {% hint style="info" %} Please note that a simulation can only be cloned if the local simulation settings are in agreement with the global settings of the building blocks, as indicated by **green check marks**. {% endhint %} ### Comparison chart for individual or population simulations in one plot The comparison chart function allows for comparison of results of different individual or population simulations in one plot. To create a comparison plot for simulation in individuals proceed in the following way: * Click on the **Comparison Chart** button in the Ribbon group **Simulation** and select **For Individual Simulations**. A new entry in the Simulation window will appear, **Comparison Chart 1**. ![The Comparison chart for comparing simulations in individuals.](/files/-LOWQ5BZqo0N33763G1c) * Open the comparison chart (if not already open). An empty chart will be displayed. * Drag and drop the simulations you want to compare from the Simulation window into the empty comparison chart. ![Drag and drop of simulation results into the comparison chart.](/files/-LOWQ5BbS1xmp2r8TJB2) * Select the simulated curves you would like to display in the comparison chart. ![Comparison Chart: Select the compartments for which simulated curves are to be displayed.](/files/-LOWQ5BeQgnGKBKInpkv) * If desired, add observed data from the building block by drag and drop to the chart. {% hint style="info" %} To rename a comparison chart, right mouse click on the respective summary chart in the Simulation window, select **Rename** and enter the new name of the chart. {% endhint %} PK-Sim® offers a comparison chart also for population simulations. To create a comparison plot for simulations in populations proceed in the following way: * Click on the **Comparison Chart** button in the Ribbon group **Simulation** and select **For Population Simulations**. A new window **Select simulations to use in comparison** opens up. Select the simulations you want to compare by ticking the respective boxes. In addition, you can select a population as a reference population and specify labeling, symbol and color for plotting. ![Select population simulations that you want to compare.](/files/-LOWQ5BjzRwG3ADLPR8Y) * When you have approved your selection of the curves by clicking OK, the **Comparison chart** chart offers you to look at the distribution of population parameters in the set union of the populations. ![The Distribution tab of the Comparison Chart displays the distribution of population parameters in all populations.](/files/-LOWQ5Bll6h4WxaswoWR) * You can then select the analysis type for your comparison from the **Analysis** button and then proceed with selection output and grouping criteria as described above. {% hint style="info" %} For a comparison of populations, only the intersecting set of output appears, e.g. if you selected venous plasma concentrations as output in all populations, it appears in the list of **Outputs** in the time profile analysis tab. {% endhint %} ![Using the Comparison Chart combined with grouping of output allows a differentiated view of the results of population simulations.](/files/-LOWQ5BnVxuQNVxtxh1T) If you define a population as a reference population, it will not be grouped into subpopulations. This might be useful when you want to compare variability in subgroups of one population with the variability of a reference population. This is illustrated below. ![Box Whisker Analysis of two populations in a Comparison Chart without defining a reference population.](/files/-LOWQ5BqttaFSa4SYZH-) ![Box Whisker Analysis of two populations in a Comparison Chart defining one (the adult) population as reference population.](/files/-LOWQ5BtL7Jjn3Z_wrmx) # Importing and Exporting Project Data and Models ## Importing Observed data The Open Systems Pharmacology Suite offers a convenient handling of experimental time-values data. The process of loading of observed data from file formats like MS Excel, CSV, or NONMEM, is described in [Shared Tools - Import and edit of Observed Data](/shared-tools-and-example-workflows/import-edit-observed-data). ## Importing Individual and Population Simulation The **Import** function of individual and population simulations allows you to use simulations that have been modified outside of PK-Sim® - most likely using MoBi® - in the PK-Sim® environment. This has several advantages: * Simulations are handled in the well-known PK-Sim® environment. * Performing population simulations with models extended in MoBi. * Performing PK parameter analyses with models extended in MoBi. #### Loading an individual simulation A simulation previously exported as a \*.pkml file from PK-Sim® or MoBi® can be imported into the current project. To import an individual simulation: * Click on the **Import/Export** tab then click on the **Individual Simulation** icon and select the \*.pkml file to be imported. The simulation will be imported into the project and will be available from the Simulation Explorer. * Imported simulations can be run and analysed as any standard PK-Sim® simulation. However, the structure of the simulation cannot be altered. That means that it is not possible to swap parts of the simulation using the building block concept described in [Modules, Philosophy, and Building Blocks](/open-systems-pharmacology-suite/modules-philsophy-building-blocks). * If an imported simulation contains parameters that are unknown in PK-Sim®, they can be found in the simulation parameter tree under the node MoBi®. #### Loading a population simulation Similarly to individual simulations, a simulation previously exported as a \*.pkml file from PK-Sim® or MoBi® can be imported into the current project as a population simulation. As the \*.pkml exports only contain individual simulation and no information about the population, population information must be either a) loaded from a \*.CSV file (e.g., previously exported from PK-Sim or created in R), or a Population Building Block must be created and assigned to the simulation. To import a population simulation: * Click on the **Import/Export** tab, then click on the **Population Simulation** icon . In the **Simulation** section of the "Import Population Simulation" dialog, select the \*.pkml file to be imported. * In the **Population** section, the population needs to be specified. There are **three** different ways of defining the aforementioned population: 1. Use a population that is defined as building block in your current project. Available populations are itemized in the drop down menu of the **Population** field. In addition, you can define a new population by clicking on the **Add** button or load a population from a template by clicking on the **Load from template** button. 2. Load a population from a .CSV file. This is a file that was previously generated from a population and saved in CSV format. * Use this option if you want to manually modify the default distribution generated by PK-Sim® for a given parameter or if you wish to vary parameters that were created in MoBi® and that PK-Sim® is not aware of. The file is selected by specifying the population file path. 3. Allocate the number of individuals. This is typically used when importing a simulation that was entirely created in MoBi® and is not based on a PK-Sim® model. In that case, all distributed parameters defined in the simulation will be randomly varied according to their distribution. Also all parameters marked with the flag “Can be varied in a population” in MoBi® can be varied manually after importing in the **User Defined Variability** tab of PK-Sim®. ## Export To Excel® You can export the simulation results (time-values profiles within all included organs and compartments) to MS-Excel®. * Right mouse click on the simulation name within the **Simulations Explorer** and select **Export results to Excel** A window opens where you can enter the Excel® file name and the file type (\*.xls or \*.xlsx). Then Excel® is automatically started showing the exported data. ## Export To CSV You can export the simulation results (time-values profiles within all included organs and compartments) to a text file in CSV format. The procedure is identical to the export to Excel®. ## Send To MoBi® You can export a PK-Sim® simulation to MoBi® by one of the following steps: * Right mouse click on the simulation name within the **Simulations Explorer** and select **Export To MoBi...** The program MoBi® will open with the exported simulation. You can then save the exported simulation within MoBi® in MoBi® format (\*.mbp3 file). ## Export to \*.pkml file for MoBi® The **Shared Modeling File (\*.pkml)** can be used to transfer a PK-Sim® simulation into a MoBi® project. To export a PK-Sim® simulation to a \*.pkml file: * Right mouse click on the simulation name in the **Simulations Explorer** . and select **Save Simulation to MoBi pkml format ...** A window opens where you can choose the directory and enter the \*.pkml file name. The file is saved an can be subsequently opened from MoBi®. {% hint style="info" %} The "Send to MoBi®" function described above is identical to exporting a simulation to a \*.pkml file and then opening this file from MoBi®. {% endhint %} ## Exporting Simulation Structures To File You can export a PK-Sim® simulation to a text file that contains all model and simulation details: model structure, rate equations and parameter values. You can export the simulation by: * Right mouse clicking on the simulation name within the **Simulations Explorer** and selecting **Export Simulation Structure To File...** A window opens where you can choose the directory and enter the file name. The file is saved and can be opened with a suitable text editor. ## Exporting the Project History To File To export the project history that contains any user action to an Excel® file: * Click on the **Export History** icon in the **Export Project** group of the **Import/Export** tab. A window opens where you can choose the directory and enter the Excel file name. ## Exporting Population data To export the physiological parameters which are varied within a population to a table (\*.csv format): * Right mouse click on the population name within the **Building Blocks Explorer** and select **Export To CSV...** * If you have created a population simulation, you can also export the population data by right mouse click on the simulation name within the **Simulations Explorer** and select **Export To CSV...**. ## Exporting Project to Snapshot / Loading Project from Snapshot PK-Sim includes various structural models together with relevant physiological and molecular databases for PBPK modeling of small and large molecules in different animal species and human populations. Relatively few inputs from the user are required to setup a complete PBPK model. Model and/or data information stored in PK-Sim databases may change over time (e.g. in order to reflect the newest scientific findings) and be incorporated into newer PK-Sim versions. Please ensure you have the latest version installed. If an old project is simply opened with a new PK-Sim version, it will contain **old** model information, **old** anatomical/physiological data etc. and will not make use of improvements in the new version. The most appropriate way to incorporate the new knowledge would be to **recreate, from scratch**, the existing project in the new PK-Sim version. To simplify this task, PK-Sim offers a concept of **project snapshots**. A project snapshot contains the **minimal amount of information** required to recreate the project from scratch. This includes the information on primary substance specific input parameters (e.g., molecular properties like *molecular weight*, *lipophilicity*, etc.) and the required inputs (e.g., demographic characteristics) for defining the system parameters. Further, any changes made in the existing model, such as a change in liver volume, will be stored in the snapshot and included in the new model once recreated from the snapshot. Project snapshots are human-readable text files in [JSON format](https://en.wikipedia.org/wiki/JSON). ![Snapshot example](/files/-LQ9BVRRIjZshQkBtkSB) The following PK-Sim entities are currently supported by snapshots and will be recreated when a project is loaded from snapshot: * All building block types (incl. observed data) * Simulations * Parameter Identifications * Simulation comparisons The following PK-Sim entities are not yet supported: * Sensitivity Analyses To export a project to snapshot, select **File** :arrow\_right: **Export to Snapshot** {% hint style="warning" %} Snapshots for a project created with a version of PK-Sim <=7.2 might be incorrect. In this case PK-Sim will warn you. If exported anyway, the new project created from this snapshot may have some undesired deviations from the original projects, which must be corrected manually by the user. Snapshot export warning {% endhint %} To load a project from snapshot, select **File** - **Load from Snapshot** {% hint style="info" %} When loading a project from snapshot, you can select whether to **run the simulations immediately** after loading or not. Not running the simulations can significantly speed up the loading process, especially for large projects with many simulations. {% endhint %} # Conversion of Projects from Previous Version Starting with version 9, the following restrictions will be implemented: PK-Sim: Only PKSim project created with version 6.0 and above can be converted to the new version. MoBi: Only MoBi project created with version 6.0 and above can be converted to the new version. # Command Line Interface - CLI CLI allows batch processing of multiple projects in PK-Sim. To start PK-Sim CLI: * Open windows command prompt (`cmd`) and switch to PK-Sim installation folder. * Enter `PKSim.CLI --help` to show the list of available commands * Enter `PKSim.CLI --help` (e.g. `PKSim.CLI snap --help`) to show options for a command ![cli](/files/-LQA9vSZjZU_m6zGPH2X) # MoBi Documentation # First Steps This section guides you to your first project with MoBi® and familiarizes yourself with the software's user interface. If you are already familiar with MoBi® and want to learn about the modularization concept, please refer to [Modularization concept](/working-with-mobi/mobi-documentation/modularization-concept). First, the window structure of MoBi®and the basic steps for setting up a new MoBi® project are described, followed by a description on how to set up and carry out a simulation. Additionally, the import of a PK-Sim® simulation is explained. However, more sophisticated applications can be performed in MoBi®, and you are referred to the following chapters for a more detailed description. To create your first MoBi® project, simply follow the steps described in the sections below. ## MoBi® - Window Overview In this section, we give a brief overview of the MoBi® window architecture and introduce some nomenclature. A typical MoBi® window looks like screenshot below. The window contains different subviews; although some of them are visible only after creating a project, we describe them right here in a comprehensive way. ![MoBi® window](/files/-LOWQ5VONrZIpWaZ6sLH) * The tabs **File**, **Modeling**, **Parameter Identification & Sensitivity**, **Working Journal**, **Import/Export**, **Utilities**, and **Views** with the **Ribbon Bar**. Additional tabs may appear depending on the context, e.g. when editing a building block or a simulation. * The **Modules Explorer** in the upper left section, which gives access to all modules and their building blocks, the individuals, expression profiles, and observed data of the current project, * The **Simulation Explorer** in the bottom left section, which lists all Simulations, Parameter Identifications, Sensitivity Analyses, and Results (comparisons) views defined in the current project, * The **History Manager** at the bottom that shows the history of model development, * The **Building Block Editor** with a building block specific layout. Generally, it consists of a **List**, **Tree**, or **Diagram Area** of all elements of the building block and a **Properties Editor** where you can edit the properties of the selected Element. You can rearrange the window by different actions: * Click ![Image](/files/-LOWQ5VW8kPS2NVlV0ZK) to hide the ribbon bar or ![Image](/files/-LOWQ5VaEObrECnbkZwJ) to show it, * Click ![Image](/files/-LNl8PnfBnAMbSc04a_n) to auto hide the **Building Block Explorer**, the **Simulation Explorer** or the **History Manager** or ![Image](/files/-LNl8PnfBnAMbSc04a_n) to dock it, * Click ![Image](/files/-LOWQ5Vi9QgiA6AqEeqT) to close these views or click the corresponding symbol in the Views group in the **Utilities** ribbon bar to open it, * Furthermore, you can drag these views and dock them to a different location. To do so, click on the title bar of the view, drag it around and drop it on one of the icons like ![Image](/files/-LOWQ5VlL7-TI6MQ7HiE) ![Docking a window to different positions](/files/-LOWQ5Vnobe8Z7Znh4vx) In the following we describe some details of the different subviews. The **ribbon bar** offers access to the various functionalities of the application. ![Ribbon Bar for selection of different functionalities in MoBi®](/files/-LOWQ5VqUqUwnaWXY-ka) The **Modules Explorer** shows all modules with their building blocks **Spatial Structures**, **Molecules**, **Reactions**, **Passive Transports**, **Observers**, **Events**, **Parameter Values**, **Initial Conditions**, and the building blocks for **Individuals** and **Expression Profiles** that are located outside of the modules. Additionally, you may find imported observed data in the modules explorer. More information on the concept of modules can be found in [Modularization concept](/working-with-mobi/mobi-documentation/modularization-concept). The different building blocks are explained in [The Building Block Concept](/working-with-mobi/mobi-documentation/building-block-concepts). {% hint style="info" %} For convenient organization of the project, modules can be grouped in folders in the Modules Explorer. {% endhint %} An in-depth explanation on how to create simulations from the modules can be found in [Setting up a Simulation](/working-with-mobi/mobi-documentation/setting-up-simulation). Once you have defined the simulations in the current project, the **Simulations Explorer** lists all of them. For details, see [Simulation Results](/working-with-mobi/mobi-documentation/simulation-results). The **History Manager** lists all modeling steps and gives the opportunity to look at earlier versions and thus at the modeling history of the project. For details, see [History Manager and History Reporting](/shared-tools-and-example-workflows/history-manager-history-reporting). ## Import PBPK Models from PK-Sim® To develop a model in MoBi®, you can either create it from scratch or import a PBPK model from PK-Sim® and extend it. To import a PBPK model, proceed as follows: 1. In PK-Sim®, create a simulation with the desired compound and individual. 2. Save the simulation as `*.pkml` file (see [Export To MoBi®](/working-with-pk-sim/pk-sim-documentation/importing-exporting-project-data-models#export-to-pkml-file-for-mobi)). 3. Start MoBi®. 4. Open the `*.pkml` file using the **File** menu and choose the **Open Simulation** command. The simulation is loaded into MoBi® as a separate **PK-Sim module**. Additionally, an Individual and a set of Expression Profiles are created in the **Modules Explorer**. Furthermore, observed data are imported if they were part of the PK-Sim® simulation. ![Imported PK-Sim® Module](/files/4Ro61Og4F1BmVYowG81G) To add extensions to the PK-Sim® module, create an **Extension Module**. To do this, right-click the **Modules** folder in the **Modules Explorer**, and select **Create Module...** from the context menu. A new window titled "New Module" will open. Enter a name for the new module (e.g., "Cimetidine Extension"), select the building blocks that should be created in the module, select the merge behavior (see [Modularization concept](/working-with-mobi/mobi-documentation/modularization-concept) for details), and click **OK**. The new module will appear in the Modules Explorer. {% hint style="info" %} You can always add building blocks later if you did not select them when creating the module. {% endhint %} ## Create a Project from scratch Alternatively, you can create a new project from scratch. The first step to start working with MoBi® is to create a new project. To do this, click on **New** in the **File** menu. You can either work with amount or concentration based reaction networks which needs to be specified when creating a new project. Create a new module, and create all building blocks in it by selecting them in the "New Module" window. See description of the building blocks on how to populate them with the required information. ## Create and Run a Simulation With a model imported from PK-Sim® or created from scratch, you can now create and run a simulation. To do this, follow the steps below: 1. In the ribbon tab **Modeling**, click the **Simulation**. The simulation creation wizard allows you to enter simulation name, select the modules to combine, and choose the individual and expression profiles. 2. Enter the simulation name. 3. Select the modules to combine (e.g., the PK-Sim® module and the extension module you created earlier). ![Simulation Configuration Dialog](/files/rEStAKFElDee0hOJif1x) 3. Click "Next >". 4. Select the individual and the expression profiles you want to use for the simulation. ![Simulation Configuration Dialog - selection of Individual and Expression Profiles](/files/sl71FPPYNX4dvij0x5jB) 5. Click "OK". 6. Click the orange arrow ribbon button to run the simulation, or alternatively press the **F5** key. After the computation is done, the simulated results are displayed in the **Results** tab. On the right, a vertical **Chart Editor** panel is visible. The **Chart Editor** allows you to select the data to be displayed in the chart, and to customize the chart appearance. See [Chart Component](/shared-tools-and-example-workflows/chart-component) for details. # Options MoBi can be customized using several options. To do this, click on the **Options** Button within the **Utilities** Ribbon Tab. **Active skin**: The program's graphical appearance can be changed by changing the skin in the Skins group next to the Options icon. ## General Tab * **Rename Dependent Elements**: When renaming an element (e.g., a container in the spatial structure), all dependent elements (e.g., neighborhoods, passive transports, initial conditions, observers) will be renamed automatically to maintain consistency. If this option is disabled, only the selected element will be renamed, and all dependent elements will keep their original names. This may lead to inconsistencies in the model. {% hint style="warning" %} Always check which elements are renamed when this option is enabled. Sometimes, not all suggested renamings are desired {% endhint %} * **Number of recent file items shown**: Changes the number of recent documents displayed within the File Tab. The program needs to be restarted for the changes to take effect. * **Decimal places**: Changes the number of decimal places shown in numerical fields throughout the application. * **Max. number of processors to use**: Changes the maximum number of processors used for tasks that can be executed in parallel (population simulations, parameter identification, parallel execution of simulations). ### Validation Options * **Show warnings from PK-Sim standard observers**: If selected, warnings will be generated if observers imported from PK-Sim (e.g., plasma concentration observer) cannot be created. E.g., if you add an organ tagged with "TissueOrgan" but without the "Intracellular"-compartment - MoBi will try to create a "Tissue" observer in this new organ and fail. The simulation will still be created, but a warning will be shown or not depending on this option. * **Show warnings for unresolved endosome containers**: When creating a simulation for small molecules model (without the `Endosome` container), some of the parameters of protein expression will not be created, as they refer to the `Endosome` container. If this option is enabled, a warning will be shown in the **Notifications** view if such unresolved containers are detected. See the [GitHub discussion](https://github.com/Open-Systems-Pharmacology/MoBi/issues/1112) for more details. * **Validate dimensions**: Enables or disables dimension validation for formulas. If enabled, the application will check if the calculated dimensions of formulas are consistent with the dimension of the entity the formula is assigned to. If the dimensions are inconsistent, a warning will be shown in the **Notifications** view. * **Show warnings when formulas dimension could not be calculated**: If enabled, a warning will be shown in the **Notifications** view if the dimension of a formula could not be calculated. * **Show known dimension warnings for PK-Sim parameters** * **Validate value constraints**: Enables or disables value constraint validation for parameters. If enabled, the application will check if the values assigned to parameters are within the defined constraints (e.g., min/max values). If a value is outside the constraints, a warning will be shown in the **Notifications** view. * **Perform circular reference check** ## Diagram Options Tab ## Chart Options Tab * **Show Simulation Name in Curve Name**: If enabled, the name of the simulation will be included in the name of the curves in charts. * **Show Top Container Name in Curve Name**: If enabled, the name of the top container will be included in the name of the curves in charts. * **Default layout**: * **Default chart y scale**: Default scaling (lin or log) of the y axis in new time-profile charts. * **Color group observed data from same folder when dropping to chart**: If enabled, when adding observed data sets to a chart via drag-and-drop from a folder (or multiple folders) within the "Observed Data" group, all data sets within one folder will get the same color. ## Default Display Units Tab ## **Application** Tab * **PK-Sim executable path**: Path to the location of the PKSim.exe file * **Use watermark**: If enabled, a watermark will be displayed in the background of the charts. # The Building Block Concept The **Building Block (BB)** concept in MoBi® offers large flexibility during model creation and reusability of model parts. The building block concept focuses on the actual physical interactions of the components in a system, i.e., once two molecules are defined as associated reaction partners, they may interact in any compartment of a system given their simultaneous availability. This availability, in turn, is dependent on the structural organization of a model, i.e., if two containers are linked by so-called neighborhood relation and if active or passive transport of the components is generally possible. The building block concept thus greatly supports the structural separation between properties of the compound which are defined by basic physico-chemistry of the molecule, and the physiology of the organism which is set by organism-specific parameters in the fundamental spatial structure of the model. There are 8 different building blocks types that are organized in modules: * **Spatial Structure** * **Molecules** * **Reactions** * **Passive Transports** * **Observers** * **Events** * **Initial Conditions** * **Parameter Values** Additionally, the building block types **Individuals** and **Expression Profiles** are organized separately and can be used in simulations with different modules. The following sections give a brief overview of the different building blocks. More detailed information on each building block can be found in separate sections for each building block. ## Exporting and importing building blocks All building blocks can be saved as a `*.pkml` file and imported into a new module from the file. To **save** a building block as a `*.pkml` file: 1. In the Modules explorer, right-click the building block of interest, and select **Save As** from the context menu. 2. Select a location where it is saved in the file browser window that will open and select a name to save it. To **import** a building block from a `*.pkml` file into a module that *does not have this BB type yet*, right-click on the module and select **Load Building Blocks**. An exception is the building block types **Parameter Values** and **Initial Conditions**, which can be imported into modules that already contain these BB types. Also, you can use any saved building block to **load individual entities** from it, e.g., individual molecules, reactions, passive transports, or observers. ## Spatial Structure The spatial structure building block defines the structural organization of the model. It contains the containers (e.g., organs, tissues, blood compartments) and their neighborhood relations. The spatial structure, therefore, defines the compartments of the model and their interconnections by defining the **neighborhoods** between the containers. {% hint style="warning" %} Two different species like mice and humans are not necessarily different in their spatial structure. (By default, the spatial structures are even equal!) These two species differ in their parameter values such as organ sizes, the blood flow rates, etc. {% endhint %} ## Molecules Generally, molecules can be any kind of countable entities. Mostly, molecules will be chemical or biological compounds and can either be quantified by amount or by concentration. A molecule can either move between containers of a model (transported either by *passive* or by *active* transport processes), or be stationary, i.e., it cannot be transported between containers. In the latter case, for example, the molecule may represent a membrane-bound receptor protein Non-stationary molecules imported from PK-Sim® projects are automatically associated with their distribution calculation method (e.g., PK-Sim® standard, Rodgers and Rowland, etc., see [Distribution](/working-with-pk-sim/pk-sim-documentation/pk-sim-compounds-definition-and-work-flow#distribution---distribution-calculation)). Selection of the distribution method defines how parameters describing the passive distribution of the compound and the partitioning into the different tissues are calculated. All proteins, molecule-protein complexes, and metabolites (that are modeled as "sink", see [Definition of a metabolite in an enzymatic process](/working-with-pk-sim/pk-sim-documentation/pk-sim-compounds-definition-and-work-flow#definition-of-a-metabolite-in-an-enzymatic-process)) are also found in the Molecules building block as stationary molecules. {% hint style="info" %} Being a substrate of a transporter, unlike being the substrate of an enzymatic reaction, is considered to be a drug property. Therefore, **active transports** are found under the drug properties in the Molecules building block. {% endhint %} ## Reactions Reactions define the causal interplay of the various molecules in a model. Note that they are not associated with a particular location or container, but are rather physical rules for the interactions of the components of a system. If two molecules are defined as reaction partners, they will react everywhere in the model, as long as all reactants (and the catalyzing proteins, if required) are available in the same compartment. The inherent precondition for a reaction to be *created* in the simulation structure is that all reaction partners are present; the precondition to *really take place* is that the amounts of the corresponding partners are not equal to zero. {% hint style="info" %} Reactions are defined independent of the location and take place wherever all reaction partners are present in non-zero amounts. {% endhint %} This concept has important implications for systems where more than one molecule is of interest and hence several molecules are simultaneously included in the overall model structure. {% hint style="info" %} If both, drug A and drug B, are known to bind the same binding partner, the mere structural consideration of both binding reactions leads to **competitive binding**, if the availability of the binding partner becomes limiting. {% endhint %} {% hint style="info" %} Drug-drug interactions, such as competitive inhibition of CYP3A4 can easily be described by defining a competitive inhibition in the reactions building block. Competitive inhibition takes place in compartments where drugs and the protein are simultaneously available. {% endhint %} ## Passive Transports The building block "Passive Transports" defines transport processes such as diffusion, convection, or transport along a lumen. Passive transports, in contrast to active transports, do not require a transporter protein to mediate the transport. Passive (as well as active) transports are only possible between containers that are connected via a neighborhood relation in the spatial structure of the model. The rules for **target** and **source** containers of a transport are defined by the *container criteria* as a mandatory condition. {% hint style="info" %} It is possible to establish passive transports like between the plasma and interstitial compartments of all organs with one equation, if the neighborhoods between these compartments were defined in the spatial structure. The kinetics for this passive distribution have to be defined only once. {% endhint %} ## Observers Observers visualize specific simulation results, while not interfering with the mass balance of the molecules under consideration. Observers can be derived by formulas including molecules and parameters. Basically, there are **Molecule Observers**, which keep track of the amount or concentration of a single molecule, and **Container Observers**, which describe amount or concentration of molecule in different containers, for which a spatial neighborhood relation was defined. Container observers can also be used to summarize amounts of several molecules within containers. {% hint style="warning" %} MoBi® internally works with amounts rather than concentrations. Hence, all concentrations in a MoBi® project are defined as observers or parameters as amount divided by volume of the compartment. {% endhint %} ## Events Events describe conditional changes during a simulation, usually a time-dependent change of values or formulas, but also complex events like drug administration, nutritional uptake, or physical exercise. MoBi®allows for any kind of change which can be described by means of an `if then else` condition. {% hint style="info" %} An event is explicitly defined by a boolean formula including an `if` condition, which often depends on time, specific parameters, or the amount or concentration of a specific molecule. {% endhint %} An important distinction is whether an event only occurs once or repeatedly whenever the condition is true. ## Initial Conditions This building block defines the start values (either as a constant value or a formula) of the molecules in the model. Additionally, Initial Conditions BB defines the containers in which the molecules will be present and whether their values may become negative. ## Parameter Values The **Parameter Values (PV)** building block defines the values (constant or formula) of the parameters in the model. Values in the PV BB always overwrite the default values defined in other building blocks such as the spatial structure or the molecules building block. Therefore, the PV BB should only contain values for parameters that are different from the default values. ## Individuals The **Individuals** building block defines the physiological properties of an individual. The parameter set referred to is limited to the parameters provided by PK-Sim®. New individuals can be created in MoBi® the same way as in PK-Sim®. ## Expression Profiles The **Expression Profiles** building block defines the expression of a protein. Technically, the Expression Profiles BB is comparable to the Parameter Values BB, containing all parameters that define the expression of a protein, and an Initial Condition for the amount and the location of the protein. New Expression Profiles can be created and the information queried from the database in MoBi® the same way as in PK-Sim®. ## Observed Data This building block includes the imported experimental (observed) data which can be, e.g., [displayed in charts](/working-with-mobi/mobi-documentation/simulation-results#observed-data) or [used for parameter identification](/shared-tools-and-example-workflows/parameter-identification). The import process is described in detail in [Shared Tools: Import and Edit of Observed Data](/shared-tools-and-example-workflows/import-edit-observed-data). # Modularization concept Starting with version 12 the OSP Suite introduces a new modularization concept for building models in MoBi. This new concept allows users to create, share, and reuse models more efficiently by breaking them down into smaller, manageable components called **modules**. This section provides an overview of the modularization concept and is especially suited for users familiar with previous versions of MoBi. It explains the advantages of using modules, how to create and manage them, and the rules that govern module combination. An example workflow illustrating how to use the modularization concept in practice can be found [here](/working-with-mobi/mobi-documentation/example-workflows#modularization-use-case---adding-a-tumor-to-a-pbpk-model). ## MoBi project structure The new concept introduces changes in how model structures are organized and combined into simulations. While OSP Suite \ **Load Spatial Structure** command in the Building Block Explorer and selecting the pkml file generated in PK-Sim® or MoBi®. ## Spatial Structures - Functionality Overview After loading a PBPK model from PK-Sim®, the spatial structure representing the whole organism is located in the imported PK-Sim® module. Double-clicking on the spatial structure () or using the **Edit** command of the context menu that appears after right-clicking on it opens an edit window. ![Spatial Structure editor overview](/files/GFAotJ8NgTUOxHRJu5J1) The right side of the window shows the structure either in a **Tree** or the **Diagram** view. The tree view shows the hierarchical arrangement of containers and neighborhoods in a tree structure. The diagram view shows the spatial structure in a graphical way. The diagram view is particularly useful for visualizing the physical and logical arrangement of containers and their neighborhoods. The tab **Formulas** shows all formulas used in the parameters of the spatial structure. ### Parent Path of Top Level Containers The spatial structures of the models are organized in a hierarchy of containers, where each container can be a child of a parent container. `Container A` can be a child of maximal one parent container `Container B`, and the parent of multiple containers. Each container has a property `Parent path` which specifies the full path to its parent container. In a module, the user can change the parent container property for the top level containers. When combining modules, the containers (and all their children) of the module will be placed under the container specified in the `Parent path` property. If the parent path of `Container A` is empty OR the container with the specified parent path is not found in the simulation, `Container A` will be created as the top-level container in the simulation. Be cautious, as changing the parent path of a container will result in different absolute path to the respective container and might break the formulas that use absolute paths for variables definition. You might have to adjust the absolute paths accordingly, by manually appending the parent path to the aliases. ### Neighborhoods New neighborhoods can be created by dragging a line from one physical container to another in the **Diagram** view, or by right-clicking on the **Neighborhoods** node in the tree view and selecting **Create Neighborhood** from the context menu. The user must specify the neighbor containers and a name for the neighborhood. If a neighborhood is defined with a neighbor that is not present in the final model structure, the neighborhood is ignored. When renaming a container, the software suggests changing the neighbor of all neighborhoods associated with the container to the new name. ### Exporting containers as pkml files As described in ["Modularization concept"](/working-with-mobi/mobi-documentation/modularization-concept), individual-specific parameters in PK-Sim modules are not stored directly in the spatial structure but in the Individual BB. When saving a container from a PK-Sim module to pkml, the user must select an Individual and, if applicable, the proteins for which the expression in this container should be allocated. This ensures that the exported container can be used without an individual. When loading a container from \*.pkml, the exported Expression Profiles are added as PV and IC. Exporting a container to PKML also exports all of its sub-containers and all neighborhoods that have this container or its sub-containers as a neighbor. ## Example - Creating a Spatial Structure {% hint style="info" %} In the process of this and the next sections of this chapter, you will create an example project. An already completed project file named "ManualModel\_Sim.mbp3" is automatically installed together with MoBi® in the default program data directory. The entry "Examples" in the program start menu in the "MoBi" group will lead you to the proper path. {% endhint %} Start by creating a new project by executing the **New Project** command in the File menu. Create a new module by selecting the **Module** button in the **Create** group of the **Modeling** tab in the ribbon. Name the new module "ExampleModule" and select a "Spatial Structure" building block to be created within the new module. Click **OK** to create the new module. The screen should now look as shown in the following figure: ![Spatial Structure as created by New Project](/files/-LOWQ5Y7IPgysKQvGs6k) In this example, you will construct a simple spatial structure which consists of a top level logical container having two interconnected physical containers. A common tag will be added to both physical containers which will be used later for restricting some computations (e.g., observers) to be only done for the two sub-containers. Tags are also used for restricting events or selecting source and target for transport processes. Check the corresponding sections for their use. ### Creating Containers and Parameters 1. Create a **top level container** by selecting **New** in the **Add** group of the **Edit Spatial Structure** tab in the ribbon, or by right-clicking on the free area of the tree view and selecting **Create Top Container** from the context menu. Enter "BigVial" as the name. Make sure that the type of the container is set to **Logical** and **OK**. 2. Now create two sub-containers. Right-click on the `BigVial` container and select **Create Container** from the context menu. A new window named "New Container" opens. Enter "Vial1" as name, and leave the Container Type on Organ. Select Physical Container in the right combobox below the name input box. 3. Click the **Add Tag** button below the Container Type. You are asked for a tag name. Enter "Obs" as a tag name. Click **OK**. ![New Container window](/files/usvcvuQas9Cdlal35MqP) 4. Repeat steps 2 and 3 to create a second sub-container named "Vial2" with the same tag "Obs". Make sure to create the second sub-container as a child of "BigVial" by right-clicking on "BigVial" and not on "Vial1"! Any container or sub-container may have parameters associated with it. They can describe physical or biological properties of the container that are required for processes like transports or reactions. What is needed in our model is the volume parameter which is used to calculate concentrations required for kinetic equations or for plotting concentrations after a simulation has been performed. To create the required parameters: 1. Expand the `BigVial` container and select the `Vial1` entry (we will refer to this container by the path `BigVial|Vial1`) 2. Click the "Parameters" tab. 3. Click the button **Add Parameter**, upon which a window named "New Parameter" opens. 4. Enter **Volume** into the Name input box, select **Volume** in the Dimension input box, then enter "0.1" into the Value input box. The Formula Type remains "Constant". 5. Finally, click **OK**, and the new parameter "Volume" will appear in the parameter list. 6. Repeat this procedure for the container `BigVial|Vial2` and set the value of the volume to 0.2 liters. ### Creating Neighborhoods Within a spatial structure, transport processes may occur (see [Active Transporter Molecules](/working-with-mobi/mobi-documentation/molecules-bb#active-transports) or [Passive Transports](/working-with-mobi/mobi-documentation/passive-transports-bb)) only between physical containers that are connected by a neighborhood. To create a neighborhood between the two containers `BigVial|Vial1` and `BigVial|Vial2`, proceed as follows: 1. Right-click on the **Neighborhoods** node in the tree view and select **Create Neighborhood** from the context menu. Alternatively, you can also use the **Neighborhood** button in the **Add** group of the **Edit Spatial Structure** tab in the ribbon. 2. Enter "V1V2Connection" as the name of the new neighborhood. Select `BigVial|Vial1` as the first neighbor and `BigVial|Vial2` as the second neighbor from the corresponding tree views. Click **OK** to create the neighborhood. {% hint style="info" %} It is possible to type in the paths to the containers instead of selecting them from the tree view. This is especially useful when the final structure with the full paths to the neighbors is a result of combining multiple modules. In this case, the containers may not yet be present in the the modules, but they will be available in the final model. {% endhint %} The created spatial structure should now look like this: ![Spatial structure with two child containers and a neighborhood](/files/cwTdJzPEG2fwirTjVLd0) By switching to the diagram view, you can see the graphical representation of the spatial structure. ![Neighborhood created between two child containers](/files/-LOWQ5YJ-MYW1lKC3rFO) Like the containers, the neighborhood may contain parameters and may carry tags. If you look at simulations imported from PK-Sim®, you will see examples for such parameters. The spatial structure of such a PBPK model is much more complex, but editing it works in the same way as described for our simple example. We will continue building our example model in the next sections by adding molecules and processes to it. # Molecules The **Molecules** building block contains all molecules with their default start values, molecule-specific parameters and properties. A molecule has a name, typically the name of the compound. Parameters and properties can be defined by you to describe the physico-chemistry, like solubility or lipophilicity. These parameters may later be used in reactions, passive and active transport processes, or may influence events. Also, active transporter molecules and active transport processes are defined for each molecule, if relevant for the model. The following section describes the functionalities of the Molecules building block based on a PBPK model exported from PK-Sim. Later on, a simple [example](#example---creating-new-molecules) is given to create a molecule from scratch. ## Molecules - Functionality Overview After loading a PBPK model from PK-Sim®, the molecules building block is located in the imported PK-Sim® module. Double-clicking on the Molecules () or using the **Edit** command of the context menu that appears after right-clicking on it opens an edit window. ![Molecules editor overview](/files/9uGOJBP4aWkMgrQifCm5) In the left part of the window, a tree view lists all molecules that are currently defined in the project. Clicking on a molecule name will highlight it and show its properties in the right part of the window. ### Molecule Properties The following molecule **properties** can be defined: * **Stationary**: If checked, the molecule will not be transported by passive transport processes. Typical molecules that are stationary are proteins (e.g., "CYP3A4", "GABRG2"), protein-drug complexes (e.g., "Midazolam-GABRG2-Buhr 1997 Complex"), or drug metabolites that are defined as *sink* (see [Definition of a metabolite in an enzymatic process](/working-with-pk-sim/pk-sim-documentation/pk-sim-compounds-definition-and-work-flow#definition-of-a-metabolite-in-an-enzymatic-process)) (e.g., "Midazolam-CYP3A4-Optimized Metabolite"). * **Molecule Type**: This has only influence on the icon depicted in front of the molecules in the molecules tree view to the right. Selectable options are Drug, Enzyme, Transporter, Complex, Metabolite , Protein, and Other Protein. * **Used calculation methods**: If the molecule is *not stationary*, it will be transported into the tissues by the *passive transports* which require some parameters that are calculated by different calculation methods. The calculation methods (e.g., for tissue partitioning) can be changed in the Molecules BB and will be applied upon simulation creation. The calculation method defines which method is used to calculate parameter values of parameters located in the **Spatial Structure** (**MoleculeProperties** node) which have the **Formula Type: Calculation Method**. These selections are only needed if you want to use distribution methods from PK-Sim®. Otherwise, leave them on "No Calculation Method". For further information on this subject, please refer to the discussion of the different distribution models in the PK-Sim® manual ([Simulations](/working-with-pk-sim/pk-sim-documentation/pk-sim-simulations)). If you select a certain "Calculation Method" you can get tool tip information on the equations and specific parameters used in the "Calculation Method" by hovering with the mouse over the "Category" entry. * The **Amount** field shows the default start amount of the molecule and can be defined either as a constant value (for drugs administered exogenously usually zero) or as a formula (e.g., for proteins, or endogenous compounds). To define different start amounts in different containers, use the **Initial Conditions** building block (see [Initial Conditions](/working-with-mobi/mobi-documentation/initial-conditions-bb)). ### Molecule Parameters The **Parameters** tab shows a list of all parameters defined for the currently selected molecule. ![Molecule parameters overview](/files/mK9fpIPn22chrp5oInuf) Each parameter has: * a **Name**, * a **Value**, defined by a constant or a different types of formulas (compare [Working with Formulas](/working-with-mobi/mobi-documentation/parameters-formulas-tags#formulas)), * a **Dimension** (compare [Parameters](/working-with-mobi/mobi-documentation/parameters-formulas-tags#parameters)), * a **Type** (**Local** or **Global**) * **Global** parameters are considered a property of a molecule that does not depend on the location of the molecule (e.g., "Molecular Weight", "LogP", "pKa"). These parameters are listed under the molecule node in the root of the simulation tree, and are accessed by the path `|`, e.g., `Cimetidine|Molecular weight`. * **Local** parameters are parameters whose values depend on the location of the molecule, e.g., "Concentration". These parameters are listed under the molecule node in each container of the simulation tree, and are accessed by the path `||`, e.g., `Organism|VenousBlood|Plasma|Cimetidine|Concentration`. {% hint style="info" %} The goal of defining a parameter as local is to have its value differ in different containers. Therefore, the parameter should either be defined by a formula that depends on the container (e.g., "Concentration" defined as `Amount/Volume`), or be set to different values in different containers by defining molecule start values (see [Initial Conditions](/working-with-mobi/mobi-documentation/initial-conditions-bb))). {% endhint %} {% hint style="info" %} More examples for molecule parameters can be found by looking at a molecule in a simulation imported from PK-Sim®. Refer to the [general section](/working-with-mobi/mobi-documentation/parameters-formulas-tags) for more information about the different formula types used for parameters. {% endhint %} * **Container Criteria**: Container criteria can be defined for local parameters to restrict the containers in which the parameter will be created. This is done by defining tag conditions (compare [How Tags are used](/working-with-mobi/mobi-documentation/parameters-formulas-tags#how-tags-are-used---container-criteria-for-formulas-observers-transports-and-events)). If no criteria are defined, the parameter will be created in all containers where the molecule is present. An example of such parameter is `Fraction expressed interstitial` of a protein molecule, which is only relevant in interstitial spaces of organs. ![Molecule parameter container criteria](/files/3O4hngOotkvrPZ3dmm0h) ### Active transports Active transport processes of a molecule are listed as sub-nodes of the transported molecule. An active transport process requires a transporter protein. As with passive transports, active transports only affect non-stationary molecules and can only act between containers that are connected by a neighborhood. Each transporter molecule can have multiple active transport processes defined for it. Clicking on an active transport process will show its properties in the right part of the window. ![Molecule active transport overview](/files/NBWIdLkF1HQx3tijTTbP) ### Protein interactions Protein interactions of a molecule are listed as sub-nodes of the interacted molecule. Protein interactions can be induction or inhibition processes of proteins, and their set up is described in [Defining Inhibition/Induction Processes](/working-with-pk-sim/pk-sim-documentation/pk-sim-compounds-defining-inhibition-induction-processes). Note that in the Molecules BB, only the parameters of the interaction are defined. The interaction itself is modeled in the **Reactions** building block or taken into account in the equations of the active transport processes. ## Example - Creating New Molecules ### Creating a new molecule 1. Click on the **New** button in the **Add** group of the **Edit Molecule** tab, or right-click in the empty space of the Molecules tree view and select **Create Molecule...**. A new window titled "New Molecule" will open. 2. Enter a molecule name into the "Name" input box. 3. Alternatively, a molecule can be created based on a PK-Sim® template. This can be achieved by using the button **PK-Sim Molecule** in the **Add** ribbon or **Add PK-Sim Molecule** from the context menu in the diagram area. 4. Enter a name for the PK-Sim molecule and the four physicochemical properties as listed. At this point, you may already input a value for the "Default Start Amount" which is set to zero by default. Also, you may define molecule parameters after clicking on the "Parameters" tab of the "New Molecule" window (see below). Both operations, however, can also be done after the molecule is created. ![New Molecule window](/files/-LOWQ5YOgzK5V6j1ueQR) ### Adding molecule parameters As an example, create the parameter "Molecular weight" for the molecule created above. 1. Click **Add Parameter**, and a "New Parameter" window will open. 2. Enter "Molecular weight" as parameter name. 3. Select the **Parameter Type** - **Global** from the combobox. 4. Select `MolecularWeight` in the Dimension combobox - you can narrow down your search by entering the first few characters after clicking this combobox field. 5. Leave "Formula Type" on Constant and enter the molecule's molecular weight in g/mol into the "Value" input box. 6. Finally, press the **Enter** key or click **OK**. The screen should look like in the screen shot below. ![Molecule building window](/files/-LOWQ5YeUK1C4uF7f0rz) As a second example, load the parameter "Concentration" from a PK-Sim® simulation export (see [Export to \*.pkml file for MoBi®](/working-with-pk-sim/pk-sim-documentation/importing-exporting-project-data-models#export-to-pkml-file-for-mobi) for how to create such a file). 1. Click the **Load Parameter** button or select it from the context menu. 2. Select a pkml file that you previously generated in PK-Sim® and select Concentration from the list. This local parameter is defined by a formula, and it is useful to have it in every molecule which is later used in a reaction kinetic equation. {% hint style="info" %} For a detailed description of the creation and use of formulas see below, [Formulas description](/working-with-mobi/mobi-documentation/parameters-formulas-tags#formulas). {% endhint %} {% hint style="info" %} For **continuing our test project**, enter three molecules and name them "A", "B", and "C". Uncheck the checkbox ![Image](/files/-LNl8QfSrkOT_RUDh53f) **Stationary** for each molecule to allow transport processes. Set the **Default Start Amount** for molecule "A" to 50 µmol and leave "B" and "C" at the default, 0 µmol. It will be needed to practice in the next sections. {% endhint %} ### Adding Active Transports An active transport process, as opposed to a passive transport, requires a transporter molecule (like a protein channel). Unlike a chemical reaction, however, this process does not change a molecule but transfers it between containers, for example, from the intercellular space into a cell. First, an active transporter molecule needs to be defined: 1. In the molecules building block and in the molecules tree, right-click on the molecule that you want to be transported. 2. Select **Create Transporter Molecule** from the context menu. 3. You are asked for a transporter name. Either enter a new name (e.g., **PGP**), or the name of an already existing transporter molecule if the very same transporter is active for several molecules in your list and has been previously defined. 4. Press **Enter** or click **OK**. In the molecules tree, a transporter molecule is displayed, and a transporter entry is added to the molecule selected in step 1. 5. In the transporter entry below the selected molecule, you may enter a description and parameters, as for any molecule. 6. Click on the transporter molecule at the top level of the molecules tree to modify this molecule's parameters. This may be the initial amount of transporter or a concentration parameter. 7. Right-click on the transporter attached to the molecule to be transported, and select **Create Transport** from the context menu. A window named "New Transport" opens. 8. Enter a name into the Name input box, like "PGP Transport". Select the **source** and the **target** container criteria (see [How Tags are used](/working-with-mobi/mobi-documentation/parameters-formulas-tags#how-tags-are-used---container-criteria-for-formulas-observers-transports-and-events)), define a transport rate parameter, and enter a transport kinetics formula. Also ses [Creating a Passive Transport](/working-with-mobi/mobi-documentation/passive-transports-bb#example---creating-a-passive-transport) as an example on how to define a transport process. 9. The kinetics formula of an active transport process is entered into the formula input box within the Tab **Kinetic** so that the red error symbol will disappear. A typical active transport formula will be dependent on the transporter concentration, substrate concentration in source and target container, and on molecule specific parameters, like a $$K\_M$$ value for substrate and transporter. You will need to add all the required concentrations and parameters as references, or you may enter them in numeric form into the equation. Continuing with our **example project**, let us enter a transport called "PGP" for molecule "A" and a transport process called "PGP Transport A" which transports the molecule from "Vial2" as source to "Vial1" as target. As references for the transport equation, you need the concentration parameters of "PGP" and of "A" from the references tree. The alias of the PGP concentration is renamed to `C_PGP`, and that of molecule `A` to `C_A` by overriding the default names. The equation to be entered is `0.001 * C_PGP * C_A`. The figure below shows what the screen should look like after everything is properly set up. ![Active Transport has been entered](/files/-LOWQ5ZEySRoATx2aEP-) {% hint style="info" %} If more than one molecule is transported by the very same transporter, you must assign the same transporter molecule twice, i.e., with the same name under the second molecule. This will only create a new active transport, but no duplicate transporter molecule. You can then proceed like for the first molecule and create a transport process. {% endhint %} {% hint style="info" %} If two molecules compete for the same transporter, you can add inhibition terms to the transport equations that use all molecules, either as transporter substrate or as transporter inhibitor. {% endhint %} ## Loading, Editing, and Saving Molecules Alternatively to newly creating a molecule as described in the \[Example - Creating New Molecules], **molecules can be loaded from a pkml file**. This file can be * a PK-Sim® export containing molecules (see [Export to \*.pkml file for MoBi®](/working-with-pk-sim/pk-sim-documentation/importing-exporting-project-data-models#export-to-pkml-file-for-mobi) for how to create such a file), * an entire previously saved MoBi® simulation, * a saved Molecules building block from a previous project, * or a previously saved molecule file. {% hint style="info" %} A collection of template files with predefined building blocks is automatically installed together with MoBi® in the default program data directory. The entry "Templates" in the program start menu in the MoBi program group will lead you to the proper path. {% endhint %} Use one of such files and proceed in the following way: 1. Click the **Load From Template** button, or right-click into the empty space below the tab "Molecules" and choose **Load Molecule** from the context menu that appears. 2. Select a folder and then a pkml file from the file browser window that will open. 3. If the pkml file contains more than one molecule, select one or more from the list that is displayed. If one or more molecule names are already in use in the current project, you will be asked for alternative names. To **save a molecule** as pkml file: 1. Right-click on its name in the molecules tree, and select **Save As** from the context menu. 2. Select a location where it is saved in the file browser window that will open and select a name to save it. {% hint style="info" %} If you are frequently building models in MoBi® where new molecules have to be defined, it is a good idea to configure your typical **default molecule** once and save it in your working directory. You can then populate your molecules building blocks by repeatedly loading your default molecule and each time changing the name to your desired molecule names. {% endhint %} # Reactions In a **Reactions** building block (BB), all (bio-)chemical reactions which are of interest for the current project are defined. A reaction has a unique **name**, a reaction **kinetics equation**, may have **parameters**, and requires **reaction partners**. 1. In our newly created project, open the **Reactions** folder and edit the Reaction building block by either right-clicking it and selecting **Edit**, or by double- clicking on it. 2. A new tab with an empty diagram area will open. This is the work space where you can add new reactions and molecules or load reactions from other projects. Again, the ribbon of the MoBi® window changes to a reaction-related view, named "Edit Reaction". Working with reactions is done mostly using the Reaction Diagram. We describe the most important features in this section, for more details see [Diagrams Overview](/working-with-mobi/mobi-documentation/diagrams-overview) ## Reactions and Molecules When creating a simulation (see [Setting up a Simulation](/working-with-mobi/mobi-documentation/setting-up-simulation)) the reactions defined in this building block are combined with the molecules from the Molecules building block. When we use the term **Molecule** in this section we refer to Molecule names only, which define the relationship between the Reactions to the Molecules from the Molecules building block. {% hint style="warning" %} If you insert a molecule that has not yet been defined in the Molecules building block, this may cause an error later when setting up a simulation. Remember to define that molecule later. {% endhint %} To have access to molecules as reaction partners for the reactions you want to create, it is advisable to first insert the molecules that you need into the Diagram Area, our work space. Alternatively, you may insert the molecules after reactions are created. To insert molecules: 1. Right-click into the Diagram Area and choose **Insert Molecule** from the context menu that appears. A box listing all molecules available in this project will appear. 2. You can either enter a name manually into the "Molecule Name" input box, or select as many as you wish from the list below this input box. Multi-select is done in the standard Windows® way by keeping the **Shift** key (for a contiguous part of the list) or the **Ctrl** key pressed (for individual selection) followed by clicking with the mouse on the desired molecule range or molecule names. 3. Click **OK** to execute the operation. For each molecule, a green circular symbol appears in the diagram area. The added **molecules can be moved** by the mouse within the diagram area. To **create a new reaction**: 1. Click the ribbon button **New**, or right-click into the diagram area at the position where you want to have the new reaction, then choose **Create Reaction** from the context menu that appears. A new window titled "New Reaction" will open with the "Properties" tab selected. 2. Enter a reaction name into the "Name" input box, e.g., "R1". 3. Below the name, you can check the box ![Image](/files/-LNl8QfSrkOT_RUDh53f) **Create process rate parameter**. If this box is checked, a parameter which equals the reaction rate equation is automatically generated when a simulation is build. You can use this parameter to refer to the reaction rate in any equation. It can also be used to plot the reaction rate (additionally check the box **Plot Process Rate Parameter**) . 4. Next, you can choose the Formula Type from a combobox - by default, **Explicit Formula** is selected. 5. If you want to use a formula that has already been defined, you may select it from the "Formula Name" combobox. To create a new formula, click the **Add Formula** button. You will be asked for a formula name. It is a good idea to use a related name for the reaction and for the reaction's formula - you may even use the same names here. Then press **Enter** or click **OK** to return to the "New Reaction" window. 6. You may then continue to create reaction parameters (like rate constants) and the reaction formula, but that can be done later as well. 7. Finally, press **Enter** or click **OK**. ![New Reaction window](/files/-LOWQ5Ymdv3FFD9tQpDb) {% hint style="info" %} For completing our example and to get more practice, repeat steps 1 to 6 to enter a second reaction that you name "R2". {% endhint %} A **reaction triangle** symbol showing the reaction name "R1" underneath will be created in the Diagram area. This triangle has differently colored circles on its corners: * The blue circle, by default on the left, is where the educts are to be connected (see where already two reactions are present). * The green circle, by default on the right, is where the products are connected. * The red circle on the top is where reaction modifiers, like catalysts or inhibitors, are connected - i.e., the molecules that are not changed by the reaction, but influence the reaction kinetics. Like molecules, reaction triangles can be dragged with the mouse to a desired position within the diagram area. ## Connecting Molecules and Reactions Now you may want to connect molecules to the reaction and verify or change the stoichiometry. There are two ways to connect a molecule to a reaction as educt, product, or modifier: * You can either click on the corresponding circle of the reaction triangle (i.e., blue for educt) and drag it towards the desired molecule, holding the left mouse button pressed and releasing it when the connection line that is protruding from the triangle connects to the proper molecule. * Alternatively, you can drag the light-green rim of a molecule symbol towards the desired position of a reaction triangle until the connection line connects to the correct target circle. In both cases, the correct position of the mouse pointer to start the action is indicated by a change of the mouse pointer from an arrow symbol ![Image](/files/-LNl8QfnyMVMrcH1Q7dj) to a hand symbol ![Image](/files/-LNl8Qfl6F1gz0eB0LdL). As long as you keep the left mouse button pressed, the connection is not yet finalized. So, if the connection line appears to connect to the wrong target, continue moving the mouse towards the desired target symbol and only release the mouse button when the correct points are connected. You should get an arrangement like shown for reaction R1 in below. {% hint style="info" %} In case a wrong connection is established, you can click on a connection, after which it is highlighted by light green squares, and then press the **Delete** key on the keyboard. {% endhint %} ![Building Reactions: Three molecules (A, B, C) and two reactions (R1, R2) have been added to the Diagram. R1 has already been connected to its reaction educt A and product B.](/files/-LOWQ5YrT69slOwykfZW) Now, continue and check the **reaction's stoichiometry**. If you have connected one or more molecules to the reaction, you should see them appearing in the properties tab of this reaction. 1. Click the reaction triangle. Below the Diagram area, the **Properties Editor**, a three-tabbed window, is shown. 2. Click the **Properties** tab, and you see the Alias names (how they will be used in the formula, see next section), the path, and the dimension of the amount of molecules . 3. Clicking on the **Stoichiometry** tab will list the educt and product stoichiometric coefficients. By default, these coefficients are set to 1, and you need to change that manually if your reaction has a different stoichiometry, e.g., if two molecules form a dimer. ## Reaction Kinetics You are now ready to define **Reaction Parameters**, like kinetic rate constants, Michaelis-Menten parameters ($$kcat$$ or $$K\_M$$), or binding constants. These parameters will then be used for the equation that defines the reaction kinetics. A new reaction parameter is defined by the following procedure: 1. Click the Parameters tab in the edit reactions window. 2. Click the **Add Parameter** button. A "New Parameter" window opens. 3. Enter a parameter name, like "k1" as a first order rate constant in our example. 4. Select the parameter type (**Local** or **Global**). * **Global** parameters are considered a property of a reaction that does not depend on the location of the reaction (e.g., $$kcat$$). These parameters are listed under the reaction node in the root of the simulation tree, and are accessed by the path `|`, e.g., `Midazolam-CYP3A4-Optimized|Km`. * **Local** parameters are parameters whose values depend on the location of the reaction, e.g., "Km interaction factor" which is the parameter describing the change of $$Km$$ by a perpetrator, e.g., an inhibitor (see section [Defining Inhibition/Induction Processes](/working-with-pk-sim/pk-sim-documentation/pk-sim-compounds-defining-inhibition-induction-processes)). Therefore, the value of this parameter may be different in different containers depending on the local concentration of the perpetrator. These parameters are listed under the reaction node in each container of the simulation tree, and are accessed by the path `||`, e.g., `Organism|Kidney|Intracellular|Midazolam-CYP3A4-Optimized|Km interaction factor`. 5. Select the proper dimension in the **Dimension** combobox, which is Inversed Time for the first order rate constant in our example. 6. Enter a value for your parameter, 0.01 as an example. If needed, select a different dimension unit in the combobox to the right of the value input box. The parameter may also be defined by a formula or data table, or you may make the parameter state variable (compare [Parameters, Formulas, and Tags](/working-with-mobi/mobi-documentation/parameters-formulas-tags)). 7. Optionally you may enter a description. 8. Finally, press **Enter** or click **OK**. Alternatively to entering it manually, you may also load it from a file or copy and paste it from another reaction in the same way as described above, see [Parameters, Formulas, and Tags](/working-with-mobi/mobi-documentation/parameters-formulas-tags). Any setting of a parameter can be edited later, and as many parameters as you need can be added to a reaction. The figure below shows what the screen would look like after one parameter has been added. ![Reaction parameter k1 has been added to reaction R1](/files/-LOWQ5YuSEcp5osOuyUH) The following steps describe how to enter a **kinetic equation** to the reaction: 1. Click the **Properties** tab again, and notice the red error sign left of the empty input box (see lower left). Hovering with the mouse over this warning symbol will show you a tool tip with information on the validity of the equation - currently the problem is that it is still empty. Examples for kinetic equations are an irreversible term, like `k1 * A`, an equilibrium like `k1 * A - k2 * B`, or a Michaelis-Menten type of equation. 2. If you want to use relative paths, select the corresponding radio button on the right hand side, and then the corresponding reference point in the tree window that pops up. 3. All variables you use in the kinetic equation will have to be present in the reference list. The molecules that were previously drawn to the reaction (educts, products, or modifiers) are already present with their corresponding amount parameters. 4. To add the reaction parameters that you defined before to the reference list, click on the + sign next to the reaction name in the tree display in the "Possible Referenced Objects" part of the window. Drag and drop all reaction parameters that you want to use in your formula into the references area left of the tree, where product and educt molecule references are listed. 5. If you need molecular concentration parameters in the formula, select Relative path and choose one container. Open this container in the possible referenced objects tree by clicking on the + sign next to it, then open MoleculeProperties underneath it, open the needed molecule and drag the concentration parameter (which needs to be created beforehand in the Molecules building block, see [Molecule Parameters](/working-with-mobi/mobi-documentation/molecules-bb#molecule-parameters)) into the references area left of the tree. Finally, you may want to edit the automatically generated alias names to have molecule names as part of the aliases. Just click into the alias name field and edit the name. 6. Besides reaction and molecule parameters, parameters of other building blocks, like the volume of a spatial structure, might be needed. They have to be defined first, so look up the corresponding sections in this chapter to see how to do that. 7. Finally, enter your kinetic equation into the empty input box below the references; for our example, enter `k1 * A`. This will let the error symbol disappear, if everything is properly defined and if all parameters are defined in the references. {% hint style="info" %} To complete reaction R2 (created above, see [Reactions and Molecules](#reactions-and-molecules)) which you will need for continuing with the model building, connect molecule "B" as educt to R2, then "C" as product, as done for R1 in the previous section. Then define another k1 parameter for R2, this time set it to 0.005. Note that the name k1 appears twice, but is assigned to different reactions - thus they can both be separated. Next drag k1 to the references list, then enter `k1 * B` as reaction kinetics formula. We will need a working reaction system if we move on to setting up a simulation later on. If using the same rate constant name for two different reactions is too confusing, use different names for the rate constants in different reactions. {% endhint %} ## Additional Features for Editing Reactions There are more features available to handle reaction building. Some of which are briefly described here: * you can delete an object using the **Delete** key or the context menu, * you can zoom, for instance by pressing the **Shift** key and selecting a rectangle by dragging the mouse, * different layout features like usage of templates and auto layout mechanisms are available. To get more details on which techniques are available in all diagrams, see [Diagrams Overview](/working-with-mobi/mobi-documentation/diagrams-overview). Instead of the diagram area, the graphical display of all reactions, you can switch to a list view by clicking the **List** tab in the upper part of the edit window. Reactions are listed by name with their stoichiometry and kinetic equations. Right-clicking the lines allows you to edit, rename, save, and remove any reaction by selecting the corresponding entry in the context menu. # Passive Transports The **Passive Transports (PT)** building block (BB) contains all passive transport processes that are generic for all non-stationary molecules. These processes are defined by source and target containers, and a kinetic formula defining the transport rate. Examples are passive diffusion, the flow of body fluids like blood, or perfusion processes. In contrast to active transporter processes defined in the molecules building block, passive transports do not require a transporter protein. The following section describes the functionalities of the Passive Transports building block based on a PBPK model exported from PK-Sim. Later on, a simple [example](#example---creating-a-passive-transport) is given to create a passive transport from scratch. ## Passive Transports - Functionalities Overview After loading a PBPK model from PK-Sim®, a set of PTs are available in the imported PK-Sim® module. Double-clicking on the Passive Transports BB or using the **Edit** command of the context menu that appears after right-clicking on it opens an edit window. A passive transport is defined by its **source** (origin) and **target** (sink), the molecules it should be applied for, and transport rate equation defined in the **Kinetic** tab. Often, it is desired to define transport processes by a generic type of equation, e.g., *in all organs from blood to interstitial space*. This is done by selecting the corresponding container tag conditions which previously should be defined to contain such container type information (see [Creating a Spatial Structure](/working-with-mobi/mobi-documentation/spatial-structures-bb)). The usage of criteria based on tags is described in [How Tags are used](/working-with-mobi/mobi-documentation/parameters-formulas-tags#how-tags-are-used---container-criteria-for-formulas-observers-transports-and-events)). Further, passive processes that should transport all present and non-stationary molecules require a kinetic equation with generic references to molecule concentration or amount. By default, MoBi® uses relative reference paths with such generic names. This will be shown in the following example process. ## Example - Creating a Passive Transport For **creating a new transport** or loading one from a previously saved file: 1. Select the corresponding ribbon button **New** or **Load**. Alternatively, you may right-click into the empty white space in the left part of the edit window and select **Create Passive Transport** or **Load Passive Transport** from the context menu. If you choose **New** or **Create**, a window named "New Passive Transport" opens. ![New Passive Transport Window](/files/-LOWQ5Z1i6goop7CX-FH) 1. Enter a name for this transport process, for example "Diffusion". 2. Define conditions for target and source containers: * Right-click into the corresponding empty space below "Condition" and "Tag", then select a container criterion (See [How Tags are used](/working-with-mobi/mobi-documentation/parameters-formulas-tags#how-tags-are-used---container-criteria-for-formulas-observers-transports-and-events) for more information). * A window where you will be asked for the tag name will open. * A tag can simply be the name of a container of a spatial structure; you can select from the available names by clicking the drop-down arrow. In our example project, select "Vial1" as "New match tag condition" for "Source", and select "Vial2" as "New match tag condition" for "Target". * The arrangement of neighborhood connections set up in the spatial structure (see [Creating Neighborhoods](/working-with-mobi/mobi-documentation/spatial-structures-bb#creating-neighborhoods)) will restrict the pattern of transport streams. 3. Define which molecules are transported. Per default, the checkbox ![Image](/files/-LNl8Pnhk1uhOUtibRI1) **All** is selected, which means that all non-stationary molecules which are present in the corresponding compartments are transported. Exceptions can be defined in the **Exclude** List. In order to add a molecule to the Exclude List, click the **Add Molecule** button within the section Exclude List. Molecules listed in the Exclude List will not be transported. If the checkbox **All** is un-checked, you can add molecules to the **Include** List. Then, only molecules listed in the Include List are transported. 4. If the box ![Image](/files/-LNl8QfSrkOT_RUDh53f) **Create process rate parameter** is checked, a parameter which equals the transport rate equation is automatically generated when a simulation is build. You can use this parameter to refer to the transport rate in any equation. It can also be used to plot the transport rate (additionally check the box **Plot Process Rate Parameter**). 5. In order to define a transport rate, go to the Tab **Kinetic**. Select **Formula - an explicit formula** in the Formula Type combobox. 6. Click the **Add Formula** button. You will be asked for a reaction formula name. Name the formula "Diffusion". Press **Enter** or click **OK**. 7. Next you need to compile the referenced values for the diffusion formula. To have more space for easier navigation, you may either click **OK** and edit the formula in the larger space of the edit window. A **diffusion equation** typically requires you to use concentration differences between two connected containers. Also, a diffusion constant is required which may be molecule-dependent. * To have such values as molecule parameters available, you need to add them in the **Molecules** building block. * If transport rates depend primarily on the processes rather than on the molecular properties (e.g., blood vessel flow rates), it might be better to create such parameters as the properties of the neighborhood (see [Creating Neighborhoods](/working-with-mobi/mobi-documentation/spatial-structures-bb#creating-neighborhoods)). * If only one global diffusion coefficient is needed (e.g., if all molecules diffuse rather similarly), you may define it as a parameter to the transport process. Use the "Parameters" tab in the edit window of the newly created passive transport, and create a diffusion constant in the way described for the other building blocks, using the "New Parameter" button. * Another alternative is to just enter a diffusion constant as a numerical value into the formula input box, as it is done below. In any of the above cases, the tree view within the field "Possible Referenced Objects" allows you to pick parameters from a variety of building blocks. {% hint style="info" %} If you notice later that a parameter would rather be placed at another location, you can move a parameter by clicking to the left of it, pressing **Ctrl+X** and inserting it with **Ctrl+V** at the proper position. However, all "Possible Referenced Objects" list entries pointing to this parameter need to be entered again manually. {% endhint %} Continuing with our example, let us enter a simple diffusion equation based on a constant multiplied by the concentration difference between the source and the target containers. 1. Make sure that the molecules created above all have a "Concentration" parameter. If not, see [Molecule Parameters](/working-with-mobi/mobi-documentation/molecules-bb#example---creating-new-molecules) how to proceed. 2. To make the concentrations available for the diffusion formula, work with the "Possible Referenced Objects" tree view, as described in [Reaction Kinetics](/working-with-mobi/mobi-documentation/reactions-bb#reaction-kinetics). Select "Relative path", and choose `Neighborhoods|V1V2Connection` as reference point. The relative path will result in source and target molecule paths that are generic for all molecules, whereas selecting an absolute path will be molecule-specific. 3. Successively expand the "Possible Referenced Objects" tree view by clicking on the + signs to the left of "BigVial", there on "Vial1", then on "MoleculeProperties", then on "A" (or any other molecule name). The "Concentration" parameter should now appear, if present. 4. Drag and drop exactly this "Concentration" parameter to the white references area to the left of the tree. The alias name "Concentration" and the path "SOURCE|MOLECULE|Concentration" should appear in the list. 5. Then open the tree below "Vial2" -> "MoleculeProperties" -> "A" and drag exactly this "Concentration" parameter into the references as well. This time, the alias should be named "Concentration1" and the path should read "TARGET|MOLECULE|Concentration". 6. Compare your screen to to the images below. If you want to change the aliases manually, you can do so by clicking on any name input box and replace the corresponding name with another. 7. Now enter the formula `0.001 * (Concentration - Concentration1)` into the formula input box below the references. The error symbol that was displayed to the left of this input box should now disappear, if everything is typed correctly. Compare your result again with the images below. {% hint style="info" %} The resulting formula is a generic formula. The example model has 3 different molecules, "A", "B", and "C". Each of them will be transported by the above passive transport, as long as they are all present in the compartments "Vial1" and "Vial2" and the checkbox "All" is selected, which is the case in our example. {% endhint %} ![Passive Transport has been added - Properties Tab](/files/-LOWQ5ZA32Rf11GdANBD) ![Passive Transport has been added - Kinetic Tab](/files/-LOWQ5ZCyGeqhSFIL0CP) # Observers An **observer** which can be displayed in a chart (see [Simulation Results](/working-with-mobi/mobi-documentation/simulation-results)) is an output derived from one or several molecules or parameters by a defined formula. There are two classes of observers: **molecule observers** and **container observers**; creating and editing of both classes will be explained in this section. The main difference between those two classes is: * **Molecule observers** are calculated for instances of molecules in *physical containers* where these molecules are present. * **Container observers** can be calculated for *any container* (physical and logical) in the spatial structure, independent of whether a certain molecule is present in this container or not. However, even a container observer must be defined for at least one molecule, as it will be created as the property of this molecule. The following section describes the functionalities of the **Observers** building block (BB) based on a PBPK model exported from PK-Sim. Later on, a simple [example](#example---creating-observers) is given to create observers from scratch. After loading a simulation that was generated in PK-Sim® (see [Load a Simulation](/working-with-mobi/mobi-documentation/setting-up-simulation#load-a-simulation)), the PK-Sim module contains the Observers building block with the standard observers for the PBPK models. ## Observers - Functionality Overview Each observer has **container conditions** that define in which containers the observer will be created and a **list of molecules** that defines for which molecules it will be created. Container conditions explained in [How Tags are used](/working-with-mobi/mobi-documentation/parameters-formulas-tags#how-tags-are-used---container-criteria-for-formulas-observers-transports-and-events) in detail. The list of molecules can either include all molecules or it can be restricted to a list of included or excluded molecules. If an observer cannot be created because the conditions do not match any container or molecule, a warning will be issued when creating a simulation (see [Create a Simulation](/working-with-mobi/mobi-documentation/setting-up-simulation#create-a-simulation)). ## Example - Creating Observers In our **example project**, open the created **Observers** building block for editing by double-clicking it. If the observers BB was not created in the module, right click on the module and select **Add Building Blocks** and then select "Observers" from the list. For **creating a new observer** or loading one from a previously saved file, select the corresponding button **New** or **Load** from the context-dependent ribbon and there select the proper observer type. Alternatively, you may right-click into the empty white space of the edit window and select **Create Molecule (resp. Container) Observer** or **Load Molecule (resp. Container) Observer** from the context menu. If you choose **New** or **Create**, a window named **New Molecule (resp. Container) Observer** opens. ### Molecule Observers To work with molecule observers, make sure the tab "Molecule Observer" in the edit window is selected. To create a new molecule observer, use **Create Molecule Observer** as described above, upon which the "New Molecule Observer" window opens (see image below). For our test project, we want to create an observer that calculates the molar concentration from the amount of molecules, doing so for each molecule and each compartment except for "BigVial". 1. Enter the name "MolarConcentration" in the Name input box, and select **Concentration (molar)** as Dimension below. 2. Check the box **All** in the section "Calculated for following molecules". If this checkbox is selected, the observer is defined for all existing molecules. Exceptions can be defined in the **Exclude List**. In order to add a molecule to the Exclude List, click the **Add Molecule** button within the section Exclude List. The observer is not defined for molecules listed in the Exclude List. If the checkbox **All** is un-checked, you can add molecules to the Include List. Then, the observer is defined only for molecules listed in the Include List. 3. Then right-click into the white space below "In Container with", and select **New match tag** condition from the context menu. 4. You are asked for a tag name. Select "Obs" from the combobox or enter it manually. The "New Molecule Observer" window should now look like: ![New Molecule Observer window](/files/-LOWQ5ZLiNavAaLy0Oml) 5. The next step is to create the **Monitor** formula which defines how the value of the observer is calculated. At this point, at least a formula **name** is required for the observer creation; all other data like the observer formula can be defined at a later point, if needed. Click on the "Monitor" tab in the "New Molecule Observer" window. 6. Click the **Add Formula** button. You will be asked for a reaction formula name; enter the name "MolarConcentration"; if this formula name is already existing, you may select it in the combobox instead of adding a new formula. In any case, the error symbol will disappear from the "Formula Name" line as well as from the "Monitor" tab, and the **OK** button becomes active. 7. You can now continue to create the formula in the "New Molecule Observer" window.

Alternatively, you can click OK or press Enter and return to the edit window, where you need to click the "Monitor" tab again.

8. On the right hand side of the Monitor window, you will see the "References" column. The screen now looks like in the screen shot below: ![Molecule Observer formula building](/files/-LOWQ5ZORIkO3d7pbLP9) 9. The formula for molecular concentration you will need to enter is the ratio of molecule amount and container volume. For both, you need the references, similar to all previously described formulas. For the amount of molecules, this is straightforward: just drag and drop the word `MOLECULE` from the "Possible Referenced Objects" tree on the right to the white space below "Alias/Path/Dimension" on the left. The alias `M`, the path `..`, and the dimension `Amount` will appear. This alias `M` stands for the corresponding amount for each molecule the observer is calculated for, according to the conditions defined previously, visible under the "Properties" tab. 10. Since our concentration observer should be computed for containers of different hierarchical levels (in case the spatial structure will be extended in the future), you need to select "Relative Path" by clicking the corresponding radio button on the right. The first time you do that in this window, you will be asked for entering a path by the window shown below. To completely visualize the path, press the **\*** key or click on all + symbols to the left of the names. You may select any of the containers here and then use its corresponding Volume parameter; however, do not use any of the "MoleculeProperties" branches, as that would invalidate the path. To complete our example observer, click on `Vial1` and then on the OK button; see the following image. ![Select Relative Path window](/files/-LOWQ5ZQbR-F_EEdDONF) 1. In the "Possible Referenced Objects" tree, navigate to `BigVial|Vial1` and expand it. You will see the parameter `Volume` below it. {% hint style="info" %} The **Local Reference Point** can be changed any time by clicking on the **...** symbol to the right of the path. {% endhint %} 2. Drag and drop the `Volume` to the left, below the `M`. The alias `Volume`, the path `..|..|Volume`, and the dimension `Volume` should appear. Compare the screenshot below with your monitor window. 3. Finally, enter the equation `M / Volume` into the input box below the references (showing a red symbol next to it before the formula is entered), and all should look like in this image. ![Molar Concentration Molecule Observer formula including references completed](/files/-LOWQ5ZSz0abCWYX5tVp) If you have already loaded or created a concentration parameter when building the molecules (see [Molecule Parameters](/working-with-mobi/mobi-documentation/molecules-bb#molecule-parameters)), you may wonder why you cannot use this reaction parameter for the observer. This is indeed an alternative option. Instead of dragging and dropping `M` and `Volume`, you can use the `Concentration` parameter with the correct relative path, which can be found under `BigVial|Vial1|A|Concentration`. Examples for many other molecule observers can be best studied when opening the observer building block in a simulation exported from PK-Sim®. ### Container Observers To work with container observers, make sure the tab "Container Observer" in the edit window is selected. For our test project, we want to create an observer that calculates the sum of concentrations of the two metabolites **B** and **C**. This creation procedure is almost identical to molecule observers, but the paths you get are different, and you will use different properties and formulas. 1. To create a new container observer, use "Create Container Observer" as described above, upon which the "New Container Observer" window opens, similar to the molecule observer. 2. Enter "SumMetabolites" as Name, "Concentration (molar)" as "Dimension". 3. Then click the "Add Molecule" button within the section "Include List". You will be asked for a molecule name; select or enter "C" and click **OK**. 4. As container criteria, select `Match Tag: Obs`. 5. Click on the "Monitor" tab, then click the **Add Formula** button. Enter "SumMetabolites" as Formula Name. Then click **OK** or press **Enter**. (As described above for the molecule observers, you may also continue the formula work in the "New Container Observer" window.) 6. Since the display returns to the properties tab, you need to click the "Monitor" tab again. Set the relative path as described for the Molecule Observer to `Vial1`. 7. In the "Possible Referenced Objects", open the `Vial1` paths all the way down until you see the "Concentration" parameters for molecules "B" and "C". 8. Drag and drop both of them successively to the reference list. 9. Enter `Concentration + Concentration1` into the formula input box left of the red symbol , which should disappear upon completion. The screen should look like in the screen shot below: ![Container Observer for Sum of Metabolites](/files/-LOWQ5ZWdaQ_rd5ZB5sG) # Events An **event** is used to change an entity, like the amount of molecules or a reaction rate, when a given condition is met. This condition can be, for example, that a given simulation time is reached, or that the concentration of a molecule has exceeded a certain value. Thus, such a programmed event is used to reflect external changes to the simulation, like the application of a drug or a sudden physical change in the spatial structure, like a vessel rupture. A special case of an event is an **application**, which is used to apply a certain amount of a molecule to a container at a given time. This is typically used to simulate the administration of a drug to the body. Events and applications are grouped in the **Events** building block (BB). Multiple events can be grouped in event groups, and organized in a hierarchy of containers similar to that of a [spatial structure](/working-with-mobi/mobi-documentation/spatial-structures-bb). Simulations imported from a PK-Sim® project contain all defined applications and additional events, such as food administration, in the events BB. The following section describes the functionalities of the Events building block based on a PBPK model exported from PK-Sim. Later on, a simple [example](#example---creating-events) is given. Since the generation of an application in MoBi® can be rather complicated and is beyond the scope of this manual, we will restrict the description to adapting applications that were previously imported from PK-Sim®, where complex applications schemes can be generated more easily. ## Events - Functionality Overview Events are organized in a tree structure. The top level container of the Events BB can be either an **Event Group** or an **Application**. ### Event Group Event groups can combine **Applications**, **Events**, further **Event Groups**, and **Containers**. An event group can be created within: - another event group, - Application The top level event group has a *name*, the *container criteria* which determines where the events group will be created in a simulation, and a set of *parameters*. {% hint style="info" %} Like for observers, an empty criteria for the events group means that the group will **not** be created in any container! The typical criteria for the events group is the `Events` node that is automatically created in an empty spatial structure. {% endhint %} ### Application Application is a special type of an event group that is defined for a specific **molecule**. In addition to the properties of an event group, an application has to specify an **administered molecule** and the path to the **Application Molecule Builder**. * **Application Model Builder**: Applications that add molecules to the system require an application model builder that is a virtual compartment for the administered molecule. An Application can be created within: - an event group, - another application. ### Event An **Event** is the actual event that changes something in the model, like the amount of a molecule or a parameter value. Events can be created within: - an event (sub-)group, - an application. Each event has - parameters, - a start condition, - **One time** property - should the event be executed (maximal) once during the simulation? If true, the event will be executed only the first time the condition is met. If false, the event will be executed each time the condition is met. - list of assignments with - Changed entity path (parameter or molecule), - New value (or formula), - Property whether the new formula is applied only once as a calculated value at the time point of event execution, or the formula overwrites the value (or other formula). {% hint style="warning" %} ``` Setting the **One time** property to false may lead to unexpected behavior, especially if the event changes a parameter or molecule amount in a way that the event condition is always true after the first execution, e.g., with the condition `TIME > StartTimeParameters`. In this case, the event will be executed at each simulated time step after the start time. ``` {% endhint %} #### Event conditions **Event condition** is defined by a logical expression that evaluates to `true` or `false` (examples: `Time = 100` or `Some_Parameter < 0.001 AND Another_Parameter >0`). Once the equation is evaluated to `true`, the event is executed. {% hint style="info" %} Technically, the value of the equation is considered to be `true` if it is unequal to zero, and `false` if it is equal to zero. {% endhint %} See [Working with Formulas](/working-with-mobi/mobi-documentation/parameters-formulas-tags#formulas) for details on how to create formulas with conditions. {% hint style="warning" %} If an event should be repeatedly fired during the simulation (i.e., the **One time** property is set to false), and the condition depends on systems state (parameter or state variables calculated during simulation), the event will only be fired if this condition is met within the defined output interval and resolution! This may lead to unexpected behavior if the output resolution is too coarse. For example, if the condition is `Concentration > 1 && Concentration < 2` and the concentration is 0.5 at time point t1 and 2 at time point t2, but no output is defined between t1 and t2, the event will not be fired since the condition was not met at any of the output time points. A discussion on this topic can be found in the [MoBi® Forum](https://github.com/Open-Systems-Pharmacology/MoBi/issues/321). {% endhint %} #### Events assignments An **assignment** defines what should be changed when the event is executed. Each event can have multiple assignments. Each assignment has the following properties: * **Name**: A unique name for the assignment. * **Changed entity path**: Path to the parameter or molecule that should be changed by the event. * **Assignment**: New value or formula that should be assigned to the entity. * **Use assignment as value**: If true, the assignment is used as a calculated value at the time point of event execution. If false, the assignment (formula) overwrites the value (or other formula). ### Container Containers can be created within: - an event (sub-)group, - an application. A container can be either **logical** or **physical** and behaves similarly to containers in a [spatial structure](/working-with-mobi/mobi-documentation/spatial-structures-bb). The container can have tags and parameters. **Logical containers** are used to group parameters. **Physical containers** can contain parameters and molecules. Typically required for applications with transport processes as the *source* container. ### Transport Transports can be created within applications. An application transport is similar to a [passive transport](/working-with-mobi/mobi-documentation/passive-transports-bb). It defines a transport process between a *source* and a *target* container. The *source* should be a physical container within the application. The *target* can be any physical container in the spatial structure. In contrast to passive transports, it is not required to define a neighborhood between the source and the target. This neighborhood will be automatically created during simulation build. ## Example - Creating Events Continue with the simple example we have been developing in the previous sections. Open the Events building block or create a new one by right clicking on the module and selecting "Add Building Blocks". ### Event Groups and Events To **create a new event group**, either * use the **New** ribbon button, * or right-click into the white space in the event edit window and select the Create Event Group command. A window named "New Event Group" will open. Then proceed with: 1. Enter a unique name into the Name input box, like "EventGroup1". 2. Enter a condition to define for which containers the event will be applicable. In order to do so, click into the white space below the "In Container with" field, and select **Match tag** condition or new **Not match tag condition** - depending if you want to include or exclude containers with a specific name or tag. In our example project, select `BigVial` as a **Match tag** condition. This will create the event group in the `BigVial` container only. As in other instances, you may define parameters for an event group. To access the parameters window, click on the **Parameters** tab in the right part of the edit window. Entering a parameter entry works in the same way as described for molecules, reactions, or for spatial structure containers. Examples for event group parameters are values for event timing or amounts of molecules that you want to set within the individual events of this event group. ![New Event Group window](/files/-LOWQ5ZavIfnomU2n3r3) After the event group is created, individual events can be defined for this group. Right-click your event group, and you will see the options you have in the context menu. These are: * Edit - this has the same function as selecting the name. * Rename * Save As PKML - saves the selected event group to a pkml file. * Delete - deletes the selected event group. * Create Application - see [Applications](#applications). * Load Application - see [Applications](#applications). * Load Application From Template * Create Event - creates a new event within the current event group. * Load Event - loads an existing event from a pkml file. * Load Event From Template * Create Event Group - creates a new event group below the highlighted event group. * Load Event Group - loads an existing event group from a pkml file below the highlighted event group. * Load Event Group From Template * Create Container - see [Applications](#applications). * Load Container - see [Applications](#applications). * Load Container From Template To create an event, click the **Create Event** option. A window named "New Event" will open (see image below). Then proceed with the following steps: 1. Enter an event name in the Name input box, e.g. "E1". 2. If your event should only be executed once during the simulation, check the box ![Image](/files/-LNl8Pnhk1uhOUtibRI1) **One Time Event** below the name. This is a useful option if, for example, you want to set an amount of molecules to a new value at a given time. For this example, check this box. 3. The section "Condition" below the checkbox requires that you enter an event condition name, which is comparable to a formula name of a reaction or a parameter. Click on "Add Formula" and name it "E1". 4. To have more space for building the condition, close this window now by clicking **OK** or pressing **Enter** to complete the event building in the edit window. However, all required data could also be entered in the "New Event" window. ![New Event window](/files/-LOWQ5Zrw3Fa9oRZkjAo) 5. Continue working with the right part of the edit window with building the event in the "Properties" tab. From the Possible Referenced Objects tree, you need the TIME variable, which reflects the simulation time. The procedure is the same as described for referenced objects used in reaction equations (see [Reaction Kinetics](/working-with-mobi/mobi-documentation/reactions-bb#reaction-kinetics)): Drag the TIME with the mouse to the left hand side and release it in the white space below the "Alias" header under the "Condition". "Time" should appear in this field. 6. There is still a Condition equation to be entered, as indicated by the red error sign in front of that input box. The easiest way to let an event happen at a given simulation time would now be to enter the formula "Time > 500", which would execute the event at 500 minutes. The use of "> 500" instead of "= 500" is advantageous since it might well be that during the simulation, the exact value of 500 will never be assumed, depending on the time step. If you plan to quickly test different values for this time, it is advantageous to define this execution time as a parameter which can be altered in the simulation. 7. Define a time parameter as an event parameter (alternatively, it can be set as an event group parameter if it is needed in several events of this group). Click the "Parameters" tab, then the button **Add Parameter**. A "New Parameter" window opens. 8. Enter "E1Time" as parameter name. 9. Select Time from the combobox "Dimension". 10. Enter "500". If you prefer to do this in other units than minutes, you may change the dimension (e.g., to "h") in the combobox to the right of the value. 11. Click **OK** or press **Enter**. The new parameter will appear in the parameters list. 12. Click the "Properties" tab. Drag and drop the newly created parameter "E1Time" from the Possible Referenced Objects list on the right into the white space below the already added "Time" reference. To find this parameter, you need to look below the E1 event, so click on the + sign to open that part of the reference tree. In case you have defined the parameter under the event group, you will find it below the event group. 13. Enter `Time > E1Time` into the formula input box, after which the error sign to the left of it should disappear. 14. What is still needed is the assignment which determines what will happen when the event condition is fulfilled. As an example, we will set the amount of molecule "A" in the container "Vial1". To proceed, click the button **Add Assignment**. A window named "New Event Assignment" will open. 15. Enter "SetA" as name into the Name input box. 16. Click the **...** on the left hand side of the "Changed Entity" input box below Name. A window named "Select Changed Entity" will open. Select the molecule "A" in `BigVial|Vial1` as target. ![Select Changed Entity window](/files/-LOWQ5Zz1QzIJzO3mUh9) 17. Click the **OK** button. The red error symbol to the left of the "Changed Entity" input box should now be gone, and a path to molecule A, `BigVial|Vial1|A`, should be visible. 18. Check the box ![Image](/files/-LNl8Pnhk1uhOUtibRI1) **Use Assignment As Value**, then enter "50" into the Value input box. This will set the amount of molecules to 50 µmol in "Vial1" when the event is executed. Finally, click the **OK** button or press **Enter**. The screen should look like in the following image, and the event is now completed. ![Event building completed](/files/-LOWQ5_3GhDS0zQ8FmPg) Events can change a number of assignments, like reaction or transport rate constants, container volumes or neighborhood parameters. The entire formula of a reaction or transport may be changed by not checking "Use Assignment As Value" during the creation of an assignment, and by selecting Formula instead of Constant in "Formula Type". Also, you may change several assignments upon one condition: just click the button "Add Assignment" again, and you can go through the above steps 14 to 18 again and have another value changed. Instead of a one time event, you can have an **event permanently active** if you uncheck the box ![Image](/files/-LNl8QfSrkOT_RUDh53f) **One Time Event** in "Properties". In our example of setting the amount of molecule "A" to 50 µmol at above 500 minutes, this would result in keeping the amount of "A" constant at 50 µmol after 500 minutes. An assignment can be changed by the following actions: * Click the **...** symbol to the right of "Changed Entity Path", and you will see the Select Changed Entity window again to alter the above choice. * In the "New Formula" input box (or row in case of several assignments), you can change between different values or formulas for the target assignment. * The box ![Image](/files/-LNl8QfSrkOT_RUDh53f) **Use Assignment As Value** can be changed to insert a formula at the assignment. * The ![Image](/files/-LNl8RByZbYsQsNb5Xvn) symbol has the same function as the button **Add Assignment**. * Clicking the ![Image](/files/-LNl8RsPTW2x1Ae9es_5) symbol will delete the corresponding assignment. ### Applications An application is basically an event group with a more complex structure than that described in the previous section. In almost all cases, the application will be created within PK-Sim®and then transferred to MoBi®. The scope of this section will be limited to working with this recommended workflow. The image below shows two example applications imported from PK-Sim®, an intravenous (iv) and an oral administration. You can see the two application in the tree view of the event edit window. Each application consist of the application group, the application start event, and the protocol schema item. To make changes, look at the parameters of the protocol schema item, as displayed in the image. ![Example Applications](/files/-LOWQ5_AtBj7dkRYIPZQ) You may make changes in the following parameters of this group: * Altering **DosePerBodyWeight** will change the dose per kg body weight. This will only work if it was used in the original PK-Sim® project, which can be recognized by having a formula in the **Dose** parameter. * Altering **Dose** will let you change the absolute drug dose administered. If the original PK-Sim® project contained a dose per body weight, that formula will be overridden by the absolute value. * The time where the drug administration starts can be altered by changing the **Start time parameter**. * The volume of water per body weight can be changed for oral applications only by using the parameter **Volume of water / body weight**. This will only work if it was used in the original PK-Sim® project, which can be recognized by having a formula in the **Amount of water** parameter. * Altering **Amount of water** will let you change the absolute amount of water administered with the drug. If the original PK-Sim® project contained a volume of water per body weight, that formula will be overridden by the absolute value. * The other parameters of this block should not be changed. {% hint style="info" %} The descriptions at the bottom section of each parameter gives you more information on each parameter. {% endhint %} More complex changes, like changing complex dosing schemes or changing dissolution patterns, are much easier to achieve using the user interface of PK- Sim® and then exporting the corresponding simulation. Within a MoBi® project, you may then combine drug applications from several PK-Sim® exports. The following describes the workflow for this operation: 1. Save all applications of interest as PK-Sim® simulations to pkml files (see [Export To MoBi®](/working-with-pk-sim/pk-sim-documentation/importing-exporting-project-data-models#export-to-pkml-file-for-mobi)). 2. Load your MoBi® project. 3. Right-click the Events entry in the building block explorer, select **Load Event Group Building Block**. 4. Enter the name and location of your pkml file. You may be asked for a new building block name. A new Events building block is created. 5. When creating a simulation ([Create a Simulation](/working-with-mobi/mobi-documentation/setting-up-simulation#create-a-simulation)), you can now select between several possible application building blocks. {% hint style="info" %} A collection of template files with predefined building blocks is automatically installed together with MoBi® in the default program data directory. The entry "Templates" in the program start menu in the MoBi program group will lead you to the proper path. {% endhint %} {% hint style="info" %} Descriptive names for each of these applications building blocks could be helpful. Use the **Rename** function from the building block context menu for this purpose. {% endhint %} # Initial Conditions The Initial Conditions (IC) Building Block (BB) defines the containers in which the molecules will be present and their initial amounts. The following section describes the functionalities of the IC BB on a PBPK model exported from PK-Sim. Later on, a simple [example](#creating-ic-bb) is given to create a new IC BB and populate it with information. ## Initial Conditions - Functionality Overview An IC BB can contain entries for molecules in physical containers across different modules. In contrast to other BB types except for the parameter values BB, **multiple** IC BBs can be created within one module. This allows you to define different initial conditions for different simulation scenarios. For example, different initial concentrations of an endogenous molecule may represent different disease states. During simulation creation, you can select which IC BB to use. The context menu of an IC BB offers the following commands: * **Save As PKML**: Save the IC BB as a pkml file. * **Clone**: Create a copy of the selected IC BB in the same module. * **Import from Excel**: Import IC BB information from an Excel file. The excel file must have the following columns: * **Container Path**: The path of the container in which the molecule is located. Path levels are separated by `|`. * **Molecule Name**: The name of the molecule. * **Value**: The initial amount or concentration of the molecule in the container. * **Units**: The unit of the initial amount or concentration. * **IsPresent**: If `true`, the molecule is considered as present in the container. If `false`, the molecule is considered as not present in the container. * **Scale Divisor**: A number by which the value is divided. Can improve numerical stability for very large or very small values. 1 by default. * **Neg. Values Allowed**: If `true`, negative values are allowed for the molecule in the container. If `false`, negative values are not allowed. {% hint style="info" %} Values defined by a formula cannot be imported from Excel. {% endhint %} * **Export to Excel**: Export the IC BB information to an Excel file. The exported file has the same format as described for the import. {% hint style="warning" %} Only entries for molecules that are defined by a constant value (not by a formula) can be exported to Excel! {% endhint %} * **Extend from Initial Conditions Building Block**: Adds entries from the Initial Conditions BB previously exported to pkml. New values are always *added*, existing values are *overwritten*. * **Extend from Expression Profile Building Block**: Adds entries from an Expression Profile BB previously exported to pkml. New values are always *added*, existing values are *overwritten*. Useful when creating a custom expression profile as initial condition. The editor of the IC BB has the following buttons (multi-select of the rows is possible): * **Delete**: Removes the selected entries * **Refresh values**: * **Present**: Sets the IsPresent status of all selected entries to `true` * **Not Present**: Sets the IsPresent status of all selected entries to `false`. {% hint style="info" %} A molecule is considered as **not present** in a container in a simulation if the simulation configuration contains no IC BB where the molecule is marked as present in the container. {% endhint %} {% hint style="info" %} Restricting the presence of molecules to certain organs may improve your computing performance, but use it carefully to keep your model valid! {% endhint %} * **Negative Values Allowed/Not Allowed**: Toggles the setting if negative values are allowed for the selected entries. If disabled (by default for all molecules), a simulation will fail if the molecule amount becomes negative during the simulation. The table view shows the following: * **Molecule Name**: The name of the molecule. * **Path Element N**: Represents the N-th level in the hierarchical container path within the spatial structure where the molecule is located. * **Value**: The initial amount or concentration of the molecule in the container. * **Scale Divisor**: A number by which the value is divided. Can improve numerical stability for very large or very small values. 1 by default. {% hint style="info" %} Internally, very small numerical values are divided by the scale divisors to get to an order of magnitude which is reasonable for the solver. The purpose is to reduce numerical noise and to enhance computation performance. This is also important when working with a broad variety of magnitudes of values. The scale divisors specify a typical scale for each species. Per default, all scale divisors are set to 1. If you work with very small amounts and/or a broad variety of magnitudes of values and your simulation yields implausible results (numerical noise, negative values, etc.), use the **Calculate Scale Divisor** function of a simulation to adjust the scale divisor for computational purposes. {% endhint %} * **Is Present**: If `true`, the molecule is considered as present in the container. If `false`, the molecule is considered as not present in the container. * **Neg. Values Allowed**: If `true`, negative values are allowed for the molecule in the container. If `false`, negative values are not allowed, and the simulation will fail if the species becomes negative during the simulation. {% hint style="info" %} Entries for molecules and/or containers that do not exist in the final model will be ignored. {% endhint %} ## Creating IC BB To create a new IC BB in a module, right-click on the module and select **Add Building Blocks** from the context menu. In the dialog that opens, select **Initial Conditions** and enter a unique name for the new BB. Click **OK** to create the new IC BB. The new IC BB does not contain any information yet. To populate it with information, you can either import the information from an Excel or a pkml file, or create new entries. ### Extending from existing BBs The best way to add entries to an IC BB is to use the **Extend** functionality. This allows you to automatically create entries for selected molecules in all physical containers of a selected spatial structures BB. To do so: 1. Click on the **Extend** button in the **Edit** group of the **Edit Initial Conditions** ribbon tab. 2. A window opens that allows you to select a spatial structure BB and one or more molecules. This will add entries for all selected molecules in all physical containers of the selected spatial structure BB. When new entries are added, the initial values or formulas are set to their default values as defined in the selected molecules building block, and these values are used for all containers in the selected spatial structure. All molecules are set to the status `IsPresent` in all selected physical containers of the selected spatial structure BB. ### Adding new entries To manually add new entries to an IC BB: 1. Click on **New Initial Condition** button in the **Edit** group of the **Edit Initial Conditions** ribbon tab. 2. A new row is added to the table view. Enter the **Molecule Name** and the **Path** of the container in which the molecule is located. You can use auto-completion for both fields. {% hint style="info" %} The path is composed of different levels of the spatial structure. If the current view of the IC BB does not show enough columns to enter all levels (e.g., after creating a new IC BB, no path levels are shown), you can right click on any column header and select **Column Chooser** from the context menu. In the dialog that opens, you can select which levels of the spatial structure you want to be shown as columns in the table view. {% endhint %} 3. Enter the initial **Value** of the molecule in the container. The unit can be selected from a combobox. The value can be either an amount or a concentration, depending on the project settings. Alternatively, assign a formula that will be used to calculate the initial value. You can either create a new formula, select an existing one, or copy-and-paste a formula from another building block. {% hint style="info" %} For our **test model**, create new molecule start values and set the concentration of molecule "A" in "Vial2" to 0. Then, set the concentration of "PGP" to 1 µmol. {% endhint %} # Parameter Values The Parameter Values (PV) Building Block (BB) defines the values of various parameters present in the simulation structure. By default, a PV BB should only contain values that are different from the default values defined in the building blocks where the parameter is defined. Additionally, PV BB can **create** new parameters during simulation creation. The following section describes the functionalities of the PV BB. Later on, a simple [example](#creating-parameter-values-building-blocks) is given to create a new PV BB and populate it with information. ## Parameter Values - Functionality Overview In contrast to other BB types except for the initial conditions BB, **multiple** PV BBs can be created within one module. This allows you to define different parameterization sets for different simulation scenarios. For example, different parameter sets may represent different disease states or different species. During simulation creation, you can select which PV BB to use. The context menu of a PV BB offers the following commands: * **Save As PKML**: Save the PV BB as a pkml file. * **Clone**: Create a copy of the selected PV BB in the same module. * **Import from Excel**: Import PV BB information from an Excel file. The excel file must have the following columns: * **Container Path**: The path of the container in which the parameter is located. Path levels are separated by `|`. For example, `Organism|Liver`. * **Parameter Name**: The name of the parameter. For example, `Volume`. * **Value**: The value of the parameter. * **Units**: The unit of the value. {% hint style="info" %} Values defined by a formula cannot be imported from Excel. {% endhint %} * **Export to Excel**: Export the PV BB information to an Excel file. The exported file has the same format as described for the import. {% hint style="warning" %} Only entries for parameters that are defined by a constant value (not by a formula) can be exported to Excel! {% endhint %} * **Extend from Parameter Values Building Block**: Adds entries from the Parameter Values BB previously exported to pkml. New values are always *added*, existing values are *overwritten*. * **Extend from Expression Profile Building Block**: Adds entries from **Parameters** tab of an Expression Profile BB previously exported to pkml. New values are always *added*, existing values are *overwritten*. Useful when creating a custom expression profile as initial condition. * **Extend from Individual Building Block**: Adds entries from the Individual BB previously exported to pkml. New values are always *added*, existing values are *overwritten*. Useful when trying to overwrite individual-specific parameters. The editor of the PV BB has the following buttons (multi-select of the rows is possible): * **Delete**: Removes the selected entries The table view shows the following: * **Parameter Name**: The name of the molecule. * **Path Element N**: Represents the N-th level in the hierarchical container path within the spatial structure where the parameter is located. * **Parameter Value**: The initial amount or concentration of the molecule in the container. * **Formula**: The formula used to calculate the parameter value. If a formula is assigned, the value is ``. * **Dimension**: The dimension of the parameter. {% hint style="info" %} For *state variable* parameters, the **Value** is the initial value of the parameter. {% endhint %} ## Creating new parameters in simulation structure through PV BB A PV BB can be used to create new parameters that do not exist in the model yet. This can be useful to define parameters that are only relevant for a specific simulation scenario. If parameter `Param A` in the container `Organism|Organ A|Container A1` does not exist in the model yet, but is defined in a PV BB that is selected during simulation creation, the parameter will be created in the specified container with the specified value. The parameter will only be created if the parent path (i.e., `Organism|Organ A|Container A1`) exists in the model. If the parent path does not exist, the parameter will not be created and a warning will be shown during simulation creation. ## Creating Parameter Values Building Blocks To create a new PV BB in a module, right-click on the module and select **Add Building Blocks** from the context menu. In the dialog that opens, select **Parameter Values** and enter a unique name for the new BB. Click **OK** to create the new PV BB. The new PV BB does not contain any information yet. To populate it with information, you can either import the information from an Excel or a pkml file, or create new entries. ### Adding new entries To manually add new entries to an IC BB: 1. Click on **New Parameter Value** button in the **Edit** group of the **Edit Parameter Values** ribbon tab. 2. A window appears that allows you to select parameters from a path tree on the left side. The parameters are grouped as follows: * **Spatial Structures**: List of spatial structures in all modules of the project. Expand a spatial structure to see its containers (including the neighborhoods). Within the containers, you will find the parameters defined for the container and for the molecules present in the container. * **Individuals**: List of individuals in all modules of the project. Expand an individual to see its parameters. * **Expression profiles**: List of expression profiles in all modules of the project. Expand an expression profile to see its parameters. * **Events**: List of events building blocks in all modules of the project. Parameters of the reactions and transport processes are not available for selection at this point. Select the desired parameter and click **Add**. You can multi-select parameters. 3. Alternatively, you can type in the full path of the parameter in the **Parameter Paths to Add** box on the right. Multiple paths can be added, separated by a new line. For example: ``` Organism|Liver|Volume Organism|Kidney|Volume ``` 4. Click **OK** to add the selected parameters to the PV BB. The edit window of the PV BB will show the newly added parameters. {% hint style="info" %} The path is composed of different levels of the spatial structure. If the current view of the PV BB does not show enough columns to enter all levels (e.g., after creating a new PV BB, no path levels are shown), you can right click on any column header and select **Column Chooser** from the context menu. In the dialog that opens, you can select which levels of the spatial structure you want to be shown as columns in the table view. {% endhint %} ### Add Protein Expression Protein expressions are defined as a set of parameter values and initial conditions. There are several cases where you might want to add protein expression information to a PV BB: * You have created a custom spatial structure and want to add protein expression information to it. * You want to overwrite the protein expression information in a custom PV BB to reflect a specific disease state. * etc. A convenient way to add all required parameters to describe protein expression in a spatial structure is to use the **Add Protein Expression** functionality. To do so: 1. Click on the **Add Protein Expression** button in the **Edit** group of the **Edit Parameter Values** ribbon tab. 2. A window opens that allows you to select organs within spatial structures and the proteins you want to add. The expression parameters will be added to the selected organs, whereby the correct formulas will be automatically assigned. If the selected organ is present in the default protein expression BB, the values for this organ will be used. Otherwise, the default values defined in the molecule BBs will be used (usually, relative expression will be set to 0). {% hint style="warning" %} When adding protein expression for a new organ, do not forget to also add the corresponding molecule start values to the IC BB! {% endhint %} {% hint style="info" %} Only new entries are added. Existing entries are not modified. {% endhint %} ### Add Local Molecule Parameters Molecules can have local parameters that are defined for each physical container in which the molecule is present. Examples for such parameters are the **Degradation coefficient** but also expression parameters of a protein. To conveniently add such parameters for all physical containers of a spatial structure, you can use the **Add Local Molecule Parameters** functionality. To do so: 1. Click on the **Add Local Molecule Parameters** button in the **Edit** group of the **Edit Parameter Values** ribbon tab. 2. A window opens that allows you to select a spatial structure and one or more molecules. This will add entries for all local molecule parameters (defined by a constant) for selected molecules in all physical containers of the selected spatial structure. When new entries are added, the parameter values or formulas are set to their default values as defined in the selected molecules building block, and these values are used for all containers in the selected spatial structure. Only *constant* local parameters are added. If a parameter is defined by a formula, it is assumed that it should not be overwritten by a PV BB. However, the parameter can still be added manually. {% hint style="info" %} Only new entries are added. Existing entries are not modified. {% endhint %} {% hint style="info" %} Parameters defining the expression of proteins are also local molecule parameters. However, it is recommended to use the **Add Protein Expression** functionality to add such parameters, as it will automatically assign the correct formulas and values. {% endhint %} # Expression Profiles The **Expression Profile** building blocks (BB) contain the information about the expression and localization of the proteins. An expression profile is a list of parameter paths and values that define the expression of a protein, and the initial conditions of proteins molecule in different compartments. When importing a PBPK model from PK-Sim, a new expression profile BB is created for each protein defined in the PK-Sim model. In contrast to the other BB types, Expression Profiles BBs are not part of a module, but stored in a separate folder in the MoBi project explorer. They can be used in combination with any module of the project. If the module does not contain the protein defined in the expression profile, the expression profile will have no effect on the simulation. ## Expression Profiles - Functionality Overview Upon opening an expression profile BB, the editor shows three tabs: * **Parameter**: Lists all parameter values defined in the expression profile. These are typically the expression levels of the protein in different organs or tissues. * **Initial Conditions**: Lists all initial conditions defined in the expression profile. For functionality overview, see the documentation of the [Initial Conditions BB](/working-with-mobi/mobi-documentation/initial-conditions-bb). * **Formulas**: Lists all formulas used in the expression profile (for parameter values and initial conditions). Values can be edited by the user, but no new entries can be added or existing entries removed. To add expression of a protein to a new structure (e.g., a new organ), you need to create a Parameter Values BB and an Initial Conditions BB in an extension module and add the new entries there. An expression profile can be saved as pkml and loaded as a parameter values or an initial conditions BB in an Extension module. An expression profile can be exported to Excel. Two sheets will be created - one for parameter values, one for initial conditions. Only values that are defined by a constant value are exported. ## Creating New Expression Profiles New expression profiles can be created in MoBi with the access to the gene expression DB. Right-click on the **Expression Profiles** folder in the MoBi project explorer and select **Add Expression Profile**. Using the **Database Query** button in the "Parameters" tab of the editor, you can search expression profile information contained in the gene expression database. The process is described in detail in the [Gene Expression Database](/working-with-pk-sim/pk-sim-documentation/pk-sim-expression-profile) documentation. # Individuals The **Individual** building blocks (BB) contain the species- and individual specific parameters describing the physiology. An expression profile is a list of parameter paths and values that define the physiological properties of an individual. Specifically, the Individual BB contains parameters that are present only for certain species (e.g., `Organism|Lumen|Duodenum|Thickness_p1` is only present in the human species, but not in rat, `Organism|Lumen|Duodenum|Default thickness of gut wall` is present in the rat but not in human), **or** have different species-specific values (`Organism|Acidic phospholipids (blood cells) [mg/g] - RR`) **or** vary within a population (e.g., `Organism|Fat|Volume`). For convenience, parameters that are defined in the Individuals BB can be shown in the spatial structure editor by selecting an individual in the "Show parameters from individual" box. ![Spatial structure view with an individual selected](/files/5K1WtS6JsFg8VOSAj2nO) When importing a PBPK model from PK-Sim, a new Individual is created. In contrast to the other BB types, Individual BBs are not part of a module, but stored in a separate folder in the MoBi project explorer. They can be used in combination with any module of the project. Parameters that are defined in the Individual but are not present in the spatial structure are created during simulation creation. This behavior is similar to the Parameter Values BB. ## Individuals - Functionality Overview Upon opening an Individual BB, the editor shows two tabs: * **Parameters**: Lists all parameters, their values, and formula. Additionally, metadata such as species and individual characteristics (e.g., age, weight, height) are shown. Values can be edited by user, but no new entries can be added or existing entries removed. To add physiological parameters for a new structure (e.g., a new organ), you need to create a Parameter Values BB in an extension module and add the new entries there. An Individual can be saved as pkml and loaded as a parameter values BB in an Extension module. ## Creating New Individuals New Individuals can be created in MoBi with access to the physiological database. Right-click on the **Individuals** folder in the MoBi project explorer and select **Add Individual**. The process is described in detail in the [Creating individuals](/working-with-pk-sim/pk-sim-documentation/pk-sim-creating-individuals) documentation. # Parameters, Formulas, Tags, and Keywords This section describes in detail how to work with the important concepts of models building in MoBi. First, different types of [parameters](#parameters) and their properties are explained. Then, the use of the different types of [formulas](#formulas) is described. Formulas are used to define parameters, reaction kinetics, transport processes, observer equations, and molecule initial conditions. Following is the explanation of the [tag concept](#how-tags-are-used---container-criteria-for-formulas-observers-transports-and-events). Tags are widely used to define conditions for localization of observers, transport processes, events, parameters, as well as for sum formulas. Finally, the special [keywords](#keywords) that can be used in paths to define references in formulas are listed. ## Parameters ### Functionality Overview In all building blocks, there may be a need to create and edit parameters. Parameters are typically listed in a separate tabbed view, named "Parameters". A parameter is used to describe physical or physiological properties of a molecule, a reaction or transport, a spatial structure, an event or an application. For improved readability, two categories of parameters exist: "regular" and "advanced" parameters. In any parameter list, a checkbox exists above the list which is named ![Image](/files/-LNl8QfSrkOT_RUDh53f) **Show Advanced Parameters**. If this box is unchecked, the parameters tagged as "advanced" are hidden. Any parameter can be tagged as being "advanced" by checking the box ![Image](/files/-LNl8Pnhk1uhOUtibRI1) **Advanced Parameter** when a parameter is created or edited. Parameters can be created, copied, moved, edited, or loaded from a pkml file: * A parameter is added by clicking on the **Add Parameter** button that is present in a parameter tab view, or by right-clicking the building block item's name (molecule, reaction, etc.) in the tree, list, or diagram view and choosing **Create Parameter** from the context menu that appears. * Instead of creating a parameter, you may also load it from a file. Use the **Load Parameter** button or context menu entry for this purpose and select a pkml file (e.g., a previously saved building block, module, or simulation) that already contains a suitable parameter. * A third option is to **copy and paste parameters** between building block items by selecting a parameter and pressing **Ctrl+C** and **Ctrl+V** after moving to the target area and after clicking into the empty parameter space. Instead of **Ctrl+C** to copy a parameter, you can use **Ctrl+X** to cut a parameter from its current position. Within the different building blocks, there are slight differences in the procedure and in the selectable options which will be explained in the corresponding sections in this chapter. In the Molecules and Reactions building blocks, parameters may be of the types **Local** and **Global**. * **Global** parameters are considered a property of a molecule or a reaction that does not depend on the location of the molecule or reaction (e.g., "Molecular Weight" of a molecule, or a reaction rate constant). These parameters are listed under the molecule/reaction node in the root of the simulation tree, and are accessed by the path `|`, e.g., `Cimetidine|Molecular weight`. * **Local** parameters are parameters whose values depend on the location of the molecule or reaction, e.g., "Concentration" of a molecule, or the apparent $$K\_{M,app}$$ that depends on the concentration of the inhibitor (see [PK-Sim - Defining Inhibition/Induction Processes](/working-with-pk-sim/pk-sim-documentation/pk-sim-compounds-defining-inhibition-induction-processes)). These parameters are listed under the molecule or reaction node in each container of the simulation tree, and are accessed by the path `||`, e.g., `Organism|VenousBlood|Plasma|Cimetidine|Concentration`, or `Organism|Liver|Periportal|Intracellular|Midazolam-CYP3A4-Metabolization|Km_app`. Any parameter has a **Dimension**, and the value can be represented in different **Units**. The list of all supported dimensions can be found in [Appendix A.1](/appendix/appendix#a1-dimensions-and-base-units). {% hint style="warning" %} When using a parameter in a formula, the value is always internally converted to the base unit of the dimension. For example, if a parameter with the dimension "Concentration (molar)" is defined with the unit "nmol/l", its value will be converted to "µmol/l" when used in a formula. {% endhint %} A parameter can be assigned to a **Group** by selecting one of the pre-defined groups from a drop-down list. This information is used for display purposes only. By selecting the **Group parameters** box in a parameter tree view, parameters will be grouped by their assigned group name. {% hint style="info" %} It is not possible to create new groups. The list of available groups is predefined and cannot be changed. {% endhint %} In the combobox of the field **Formula Type**, you can select if the parameter is defined as: * a **constant**, consisting of a numeric value and a unit; * a **table**, using individual data pairs from which a value is interpolated over the simulated time; * a **formula**, having a formula name and a formula string (i.e., a mathematical expression) including references to the formula items; * a **table with offset**, which is a table that is reused and shifted in time by a constant time value defined in another parameter; * a **table formula with x-argument**, which is a table that is reused and evaluated at a value defined in another parameter; * a **sum formula**, which calculates the sum of all values with a certain condition; * a **calculation method** parameter, whose formula will be defined depending on the selected calculation method of each molecule in the model (only available for parameter of spatial structure container). The calculation methods cannot be edited within MoBi® and are imported from PK-Sim®. * a value **distributed** around a constant value or between two limits (only available for parameters of spatial structure containers). The different formula types are explained in the section [Formulas](#formulas). In the bottom part of the **Create** or **Edit** window are several input options that have different effects on the parameter: * Checking ![Image](/files/-LNl8Pnhk1uhOUtibRI1) **Parameter is state variable** will open additional input fields for the right hand side of a differential equation (explained in detail in [State Variable Parameters](#state-variable-parameters)). * Checking ![Image](/files/-LNl8Pnhk1uhOUtibRI1) **Plot Parameter** will tag this parameter so that it can be visualized in a chart with the simulation results (see [Chart Component](/shared-tools-and-example-workflows/chart-component)). * Checking ![Image](/files/-LNl8Pnhk1uhOUtibRI1) **Advanced Parameter** will hide this parameter from the lists if **Show Advanced Parameters** is ![Image](/files/-LNl8QfSrkOT_RUDh53f) un-checked in the parameter list view. * For all parameter types, **a description can be added** into the input box at the bottom, for example to quote a reference. Clicking into the text field will open an edit dialog into which you can enter or paste any text of your choice. You may also **add tags to any parameter** in the **Tags** tab of the parameters editor. Tags are used to label parameters for selective evaluation in sum formulas (see [Sum Formulas](#sum-formulas)). The application of tags is explained in [How Tags are used](#how-tags-are-used---container-criteria-for-formulas-observers-transports-and-events). * To add a tag, click the "Add Tag" button and enter the tag in the input box. * To delete a tag, click the symbol that appears behind every tag in the list. ### Constant Parameters A constant parameter is defined by a constant **Value**. You may use decimal points, exponential notation, and minus signs (e.g., 2.34; 1.2E-6; -150). Next to the value, its unit will be shown; the default unit is selected by your choice in the Dimension field, but it can be changed to other units listed in the combobox, e.g. from 1/min to 1/sec or 1/h. Examples for constant parameters are "Molecular weight" of a molecule or the rate constant of a reaction. ### Distributed Parameters **Distributed parameters** (only available for parameters of spatial structure containers) describe a variation around a constant value or between two numerical limits. Within a given MoBi® simulation, a distributed parameter has a fixed value (default defined by the value in the field **value**). A distributed parameter can be used only to calculate the percentile of the parameter value given a certain distribution. Distributed parameters are useful if population statistical data are to be defined within a model. To define such a parameter, use the **Create Distributed Parameter** command from the context menu of a spatial structure item, like for containers (e.g., organ sizes) or neighborhoods (e.g., blood flow rate). In addition to what is entered for constant parameters, the **Distribution Type** has to be selected. Available options are: * **Discrete Distribution**, which is identical to a *constant parameter*. This feature is implemented for the purpose of simply disabling the distribution function without going through the parameter creation process again. * **Uniform Distribution**, where a parameter will be uniformly distributed between a **Minimum** and a **Maximum**. * **Normal Distribution**, where the values of the parameter are normally distributed (Gaussian distribution) with a **Mean** value and a **Standard Deviation**. * **LogNormal Distribution**, where the values of a parameter follow a lognormal distribution with a **Mean** value and a **Geometric Standard Deviation**. If you use one of the different distributions, a **percentile** will be automatically calculated for the parameter value define in field **value** given the defined distribution. ### State Variable Parameters A parameter can also be defined as a *state variable* with a right-hand-side (RHS). This means, that the parameter value is defined by a differential equation. To do this, click the ![Image](/files/-LNl8Pnhk1uhOUtibRI1) checkbox **Parameter is state variable** when entering or editing a parameter. The value of a parameter *p*, for example, is defined by a differential equation $$\frac{dp}{dt} = RHS$$ where *RHS* is the right-hand side of the differential equation defining the *change of parameter value per unit time step*. For a *state variable parameter*, you can define the **initial value** of the parameter in the top half of the parameter edit view, as for any other parameter type. The initial value is the value of the parameter at simulation time = 0. The **Right Hand Side** is defined in the bottom part of the editor. The value of the parameter is evaluated for each simulation step according to the differential equation. {% hint style="warning" %} Once the ![Image](/files/-LNl8QfSrkOT_RUDh53f) **Parameter is state variable** checkbox is deactivated again, the input box for the RHS will disappear. The parameter is no longer a state variable, and the right hand side (RHS) formula reverts to RHS = 0. If you have accidentally deactivated the checkbox and then reactivate it, the formula you may have previously defined as RHS is not lost, since all created formulas are stored. To reinstate the formula you may have previously defined as the RHS, select the formula from the combobox after the formula type explicit formula is selected. {% endhint %} {% hint style="info" %} For state variable parameters, the values defined in a Parameter Values building block represent the initial values of the parameter at simulation time = 0. {% endhint %} ## Formulas ### Functionality Overview Formulas are widely used in OSP models to define parameters, reaction kinetics, transport processes, observer equations, and molecule initial conditions. This section describes how to work with formulas in MoBi®. All formulas defined in a building block are listed in a separate tab named **Formulas**. Clicking on a formula in the list will show the references and the equation for the selected formula. Right-clicking on a formula in the list opens a context menu that allows you to **Rename**, **Clone**, and **Remove** formulas. Formulas can be re-used, e.g., multiple parameters within a spatial structure can use the same formula. {% hint style="warning" %} If you modify a formula in the editor of a parameter or any other entity, this change will affect all other entities using this formula! {% endhint %} You can re-use formulas across different building blocks by copying and pasting them. To do so, select a formula in the formula list of a building block, press **Ctrl+C**, then move to the formula list of another building block and press **Ctrl+V**. Upon creation of a formula, it gets the dimension of the parameter or entity where it is created. For parameters, the formula gets the dimension of the parameter. For molecule start values, the dimension is "Amount". For reaction and transport processes kinetics, the dimension is "Amount per time", and for formulas used in event conditions, the dimension is "Dimensionless". The only way to change the dimension of a formula is to change the dimension of the parameter or entity to which the formula is assigned. Furthermore, a formula can only be used in entities or parameters with the same dimension. {% hint style="info" %} It is a good idea to use a name related to the object where the formula is used (e.g., parameter, reaction, observer) - you may even use identical names here. {% endhint %} To enter or edit a **formula string**, click into the unnamed input box above the **Description** field and then use your keyboard. This formula string will be evaluated by the solver once the simulation is run. It is written as a mathematical term that comprises numeric values, arithmetic operation signs, and names of parameters or their alias names. As long as the formula has errors or is incomplete, a red error sign is displayed left of the empty input box. Hovering the mouse over this warning symbol will show you a tool tip on the validity of the equation (e.g., missing references or syntax errors). ### Supported Characters and Functions in a Formula In a (explicit) formula, the following characters may be used: * numbers can be entered as described for constants, e.g. `2.34`; `1.2E-6`; `-150` (**WARNING**: a comma `,` is interpreted as a decimal point!) * `TIME` variable: The simulation time * the arithmetic operation signs * Plus `+`, e.g., `3 + 5` * Minus `-`, e.g., `3 - 5` or `-5` (unary minus) * Multiplication `*`, e.g., `3 * 5` * Division `/`, e.g., `3 / 5` * Exponentiation `^`, e.g., `3^5` = 3 to the power of 5 * round brackets **(** **)**, e.g., `(3 + 5) * 2` * the constants **pi** and **e**, representing the mathematical constants $$\pi$$ and $$e$$. * the mathematical functions * Arccosine (inverse cosine) **ACOS**, e.g., `ACOS(0.5)`, * Arcsine (inverse sine) **ASIN**, e.g., `ASIN(0.5)`, * Arctangent (inverse tangent) **ATAN**, e.g., `ATAN(1)`, * Cosine **COS**, e.g., `COS(pi/4)`, * Hyperbolic cosine **COSH**, e.g., `COSH(1)`, * Exponential function **EXP**, e.g., `EXP(1)` which corresponds to $$e^1$$, * Natural logarithm **LN** or **LOG**, e.g., `LN(e)` or `LOG(e)`, * Logarithm to base 10 **LOG10**, e.g., `LOG10(10)`, * Maximum of two values **MAX**, e.g., `MAX(3;5)` which evaluates to 5, * Minimum of two values **MIN**, e.g., `MIN(3;5)` which evaluates to 3, * Power function **POW**, e.g., `POW(3;5)` which corresponds to $$3^5$$, * Sine **SIN**, e.g., `SIN(pi/4)`, * Hyperbolic sine **SINH**, e.g., `SINH(1)`, * Square root **SQRT**, e.g., `SQRT(4)`, * Tangent **TAN**, e.g., `TAN(pi/4)`, * Hyperbolic tangent **TANH**, e.g., `TANH(1)` * the random number generator functions **RND** and **SRND**, both to be used with the dummy argument **()** * **RND** will produce the same sequence of random numbers in the interval \[0..1] every time you run your program because it starts from a default seed. * **SRND** will produce "real" random numbers. If you have a call to **SRND** in any model - all other calls to **RND** (both in this and all other models!) will produce "real" (non-reproducible) random numbers - until you restart MoBi or PK-Sim! {% hint style="info" %} The above mathematical functions are defined as in the C programming language. {% endhint %} Furthermore, defined **aliases** can be used in a formula as formula constants. ### Formula aliases - using other parameters and molecule amounts in a formula The following figure shows the formula editor window that opens when you create or edit a formula. ![](/files/TyMfrAGCAMZJW6Stxv37) Below the formula name and above the formula string, there is a **Reference Table** showing a header line above the columns named **Alias**, **Path**, and **Dimension**. On the right hand side of the reference table, there is a second table titled **References to add**. From this right part, references are moved to the left **Reference Table** by drag & drop. * The **Alias** is the name that will be used in the formula string to refer to the object. * The **Path** is the path to the referenced object (parameter or molecule amount). E.g., in a formula `3 * Conc + 5`, the alias is `Conc`, and the path could be `Organism|Liver|Plasma|Cimetidine|Concentration`. When adding references to a formula via drag & drop, you can choose between an absolute or a relative path. If you select a relative path, you will be asked to select a **local reference point**. The local reference point is the location in the model structure from which the relative path is defined. You can think of it as a *working directory*, and the paths to the selected entities will be constructed *relative* to it. See the section [The Path concept](#the-path-concept) for more information on absolute and relative paths. The selected local reference point will be displayed with its absolute path in the "References to add" window. In case you need to correct or alter the local reference point, click on the **...** icon right of the path. This will re-open the reference point selection window. To add a reference after having selected the reference point: 1. Find the reference by name in the **Possible Referenced Objects** tree. Expand the tree nodes if necessary. 2. Click on the object's name, then drag it to the Reference Table area left to it; drop it there by releasing the mouse button. The object will be added to the list, usually with its name as the alias. If that name already exists in the list, the alias name is automatically renamed by adding a running index. The path and dimension of the object are also added. {% hint style="warning" %} Not all entries in the tree are allowed to be moved to the left, depending on the context of the formula. {% endhint %} 3. If needed, you may edit the alias name of the object manually. Alias names need to be identical to the names that are used in the formula string. Simply click on the alias name and change or override (or copy/paste) the name. For example, if you added several "Concentration" parameters from different molecules to a reaction kinetics equation, it may be helpful to manually add the molecule name next to them. 4. In the same way as for aliases, it is also an option to manually edit the path. However, the standard procedure would be to remove the object and add it again, using a new local reference point. 5. Dimensions can be changed by clicking on the displayed dimension and selecting a different one from the combobox. To **remove an object from the reference list**, right-click it and select **Remove**from the context menu. ### Conditions in a Formula Logical conditions can be used in a formula to define different values depending on the fulfillment of a condition. A condition is defined using the notation ` ? : `, e.g., `TIME < 10 ? 5 : 10`, which means: "if time is less then 10, use value1, otherwise use value2". In the conditions, the following operators are supported: * Less than `<` or `LT`, e.g., `TIME < 10` or `LT(TIME;10)` * Greater than `>` or `GT`, e.g., `TIME > 10` or `GT(TIME;10)` * Not equal `<>` or `!=` or `NEQ`, e.g., `TIME <> 10` or `TIME != 10` or `NEQ(TIME;10)` * Greater than or equal `>=` or `GEQ`, e.g., `TIME >= 10` or `GEQ(TIME;10)` * Less than or equal `<=` or `LEQ`, e.g., `TIME <= 10` or `LEQ(TIME;10)` * Equal `=` or `EQ`, e.g., `TIME = 10` or `EQ(TIME;10)`. Conditions can be combined by **AND** and **OR**, or inverted by **NOT** operands. An alternative symbol for **AND** is **&**; an alternative symbol for **OR** is **|**. Besides logical conditions, the numbers 0 and 1 can be used as arguments, where 0 means `false` and 1 means `true`. {% hint style="info" %} It is recommended to use events rather than "if conditions" in a formula if the value of the entity defined by the formula is expected to change depending on the fulfillment of a condition. {% endhint %} ### Sum Formulas **Sum formulas** can be used to calculate sums of values of entities that comply with certain criteria. The criteria are defined by tags that are assigned to the entities. Tags can be assigned to containers, neighborhoods, parameters, and events (see [How Tags are used](#how-tags-are-used---container-criteria-for-formulas-observers-transports-and-events)). ### Table Formulas A parameter can be defined by a table that is made up out of pairs of simulation- time and corresponding functional value. The parameter value as a function of time that is used in the simulation will be interpolated between these values. To enter a table: 1. Select Table as **Formula Type**. 2. To create a new table formula, click the **Add Formula** button, upon which you will be asked for the formula name. Then press **Enter** or click **OK** to return to the main window. 3. In the **Formula Name** combobox, you may alternatively select an existing table formula name. 4. To add a data point, click the **Add** button. 5. Enter a time-value pair. The values must be in the unit shown in the column header. 6. You may check **Restart Solver** box in case the solver generates errors when arriving at these time points. {% hint style="info" %} Every point in the table creates a discontinuity in the derivative of the parameter. In many cases, the ODE solver handles it by restarting internally. In some situations though, the solver cannot handle such a derivative discontinuity automatically, and the user needs to manually enable the **Restart Solver** property. {% endhint %} 7. More data points can be entered by clicking **Add Value Point** again, or by clicking on the button in the right to the values lines. You can delete a data pair by clicking the **delete** button. Alternatively, you can import a table from an excel or csv file by clicking the **Import** button. The same import process is applied as for importing observed data (see [Importing Observed Data](/shared-tools-and-example-workflows/import-edit-observed-data)). If you would like to use the first derivative of the interpolation, check **Use Derivative Values**. Values before the first and after the last data point of the series are set to 0. ### Table Formulas with Offset A table described in [Working with Tables](#table-formulas) may need to be reused and shifted by a constant time value. For example, PK-Sim® uses this logic to build up repeated advanced application protocols (compare [PK-Sim® - Administration Protocols](/working-with-pk-sim/pk-sim-documentation/pk-sim-administration-protocols)). For a table formula with offset, you have to specify: * The table parameter with the **Path to table object**. Upon clicking the "..." icon, you can select an existing table parameter from a path tree. * The offset time parameter with the **path to offset object**. Upon clicking the "..." icon, you can select one such object from a path tree. This must be a parameter with the dimension `Time`. The values of the offset parameter will be subtracted from the X values of the original table at the time of evaluation. ### Table Formulas with X-Argument If a table should describe a parameter which values depend on any other parameter than the simulation time, a **table formula with X-Argument** can be used. For a table formula with X-argument, you have to specify: * The table parameter with the **Path to table object**. Upon clicking the "..." icon, you can select an existing table parameter from a path tree. * The path to the object which values will be used as X-argument. The values of the selected X-Argument will be used as x-values in the original table at the time of evaluation. The values are considered to be in the base unit. ## How Tags are used - container criteria for formulas, observers, transports, and events Containers and neighborhoods within a spatial structure, elements of an application, or parameters may be labelled with tags. These tags, together with the name given to a container or neighborhood, may be used for selectively enabling observers, active or passive transports, or events. They are used for formula evaluations of the formula type "sum". Tags can be entered when creating or editing a tag-carrying entity. The detailed procedures are described within this chapter in the corresponding sections describing spatial structures, observers, events, or parameters. Generally, one or more names are entered in a special input window of the corresponding entity. Conditions are evaluated in fields of observers, transports, or event groups titled "In Container with" or "Between Containers with". Conditions can be combined using either **AND logic** (`Condition1 AND Condition2 AND ...`), or **OR logic** (`Condition1 OR Condition2 OR ...`). Imagine the following simple model structure: ``` Organism (logical) | +-- Container A (logical) | | | +-- Container A1 (physical) | +-- Container A2 (physical) | +-- Container B (logical)) | +-- Container B1 (physical) +-- Container B2 (physical) ``` A molecule `Molecule A` is present in the physical containers `A1`, `A2`, `B1`, and `B2`. Each container has a parameter `Param A`, including the molecule. The physical containers have additionally the parameter `Concentration`. {% hint style="info" %} The following examples demonstrate the concept of tags and container criteria. They are not meant to represent a physiologically meaningful model. {% endhint %} If we create a sum formula with the following conditions: 1. **Match tag condition**: the condition is fulfilled when the tag name is matched. * For the sum formula with match tag condition "Param A", the sum will include the following parameters: * `Organism|Param A` * `Organism|Container A|Param A` * `Organism|Container A|Container A1|Param A` * `Organism|Container A|Container A1|Molecule A|Param A` * `Organism|Container A|Container A2|Param A` * `Organism|Container A|Container A2|Molecule A|Param A` * `Organism|Container B|Param A` * `Organism|Container B|Container B1|Param A` * `Organism|Container B|Container B1|Molecule A|Param A` * `Organism|Container B|Container B2|Param A` * `Organism|Container B|Container B2|Molecule A|Param A` 2. **Not match tag condition**: the condition is fulfilled when the tag name is **not** matched. * For the parameter `SumOfParameters` with the conditions `Not tagged with: Param A` and `Not tagged with: SumOfParameters` (the latter is required to avoid a circular reference), the sum will include the following parameters: * `Organism|Container A|Container A1|Volume` * `Organism|Container A|Container A1|Molecule A|Concentration` * `Organism|Container A|Container A2|Volume` * `Organism|Container A|Container A2|Molecule A|Concentration` * `Organism|Container B|Container B1|Volume` * `Organism|Container B|Container B1|Molecule A|Concentration` * `Organism|Container B|Container B2|Volume` * `Organism|Container B|Container B2|Molecule A|Concentration` **AND** molecule amounts * `Organism|Container A|Container A1|Molecule A` * `Organism|Container A|Container A2|Molecule A` * `Organism|Container B|Container B1|Molecule A` * `Organism|Container B|Container B2|Molecule A` 3. **In Container**: the condition is fulfilled by all model entities located in the specified container and its children. * For the parameter with the condition "In Container with: Organism", the sum will include the following parameters: * `Organism|Param A` * `Organism|Container A|Param A` * `Organism|Container A|Container A1|Param A` * `Organism|Container A|Container A1|Volume` * `Organism|Container A|Container A1|Molecule A|Concentration` * `Organism|Container A|Container A1|Molecule A|Param A` * `Organism|Container A|Container A2|Param A` * `Organism|Container A|Container A2|Volume` * `Organism|Container A|Container A2|Molecule A|Concentration` * `Organism|Container A|Container A2|Molecule A|Param A` * `Organism|Container B|Param A` * `Organism|Container B|Container B1|Volume` * `Organism|Container B|Container B1|Molecule A|Concentration` * `Organism|Container B|Container B1|Param A` * `Organism|Container B|Container B1|Molecule A|Param A` * `Organism|Container B|Container B2|Param A` * `Organism|Container B|Container B2|Volume` * `Organism|Container B|Container B2|Molecule A|Concentration` * `Organism|Container B|Container B2|Molecule A|Param A` **AND** molecule amounts * `Organism|Container A|Container A1|Molecule A` * `Organism|Container A|Container A2|Molecule A` * `Organism|Container B|Container B1|Molecule A` * `Organism|Container B|Container B2|Molecule A` * For the parameter with the condition "In Container with: Container A", the sum will include the following parameters: * `Organism|Container A|Param A` * `Organism|Container A|Container A1|Param A` * `Organism|Container A|Container A1|Volume` * `Organism|Container A|Container A1|Molecule A|Concentration` * `Organism|Container A|Container A1|Molecule A|Param A` * `Organism|Container A|Container A2|Param A` * `Organism|Container A|Container A2|Volume` * `Organism|Container A|Container A2|Molecule A|Concentration` * `Organism|Container A|Container A2|Molecule A|Param A` **AND** molecule amounts * `Organism|Container A|Container A1|Molecule A` * `Organism|Container A|Container A2|Molecule A` 4. **Not in Container with**: the condition is fulfilled for all model entities that are **not** in the specified container or any of its children. 5. **In Parent**: the condition is fulfilled by all model entities located in the specified container and its children. This can be considered as a special case of "In Container", where the container is the parent of the entity being considered. 6. **In Children**: the condition is fulfilled by any model entity in all children of the parent container of the entity for which the criteria is defined. * For the parameter with the condition "In Children" located in `Organism|Container A`, the sum will include the following parameters: * `Organism|Container A|Container A1|Param A` * `Organism|Container A|Container A1|Volume` * `Organism|Container A|Container A1|Molecule A|Concentration` * `Organism|Container A|Container A1|Molecule A|Param A` * `Organism|Container A|Container A2|Param A` * `Organism|Container A|Container A2|Volume` * `Organism|Container A|Container A2|Molecule A|Concentration` * `Organism|Container A|Container A2|Molecule A|Param A` **AND** molecule amounts * `Organism|Container A|Container A1|Molecule A` * `Organism|Container A|Container A2|Molecule A` More than one condition can be combined for evaluation; the combinations are connected either with a logical `AND` or a logical `OR`. The detailed procedures when and how to enter tag conditions are described in this chapter ([Sum Formulas](#sum-formulas) or [Transport Processes](/working-with-mobi/mobi-documentation/passive-transports-bb)). Models generated in **PK-Sim**® make extensive **use of tags**: For example, open a PK-Sim® model and look under [Passive Transports](/working-with-mobi/mobi-documentation/building-block-concepts#passive-transports) for one part of the blood flow through the organs of an organism called "MassTransferBloodPool2OrgPl". This is a passive transport process that occurs from the arterial plasma compartment to the plasma compartments of all organs except for the lung. Consequently, this transport process is occurring under the following conditions: 1. Source container: tagged with "Arterial Blood" and tagged with "Plasma". 2. Target container: tagged with "Plasma" and not tagged with "Arterial Blood" and not tagged with "Lung". Similarly, observers or events can be included or excluded from being created in different parts of the spatial structure. The molecule observer "Fraction excreted", for example, makes use of the tag "Urine", so this observer is only created in the urine container. ## The Path concept Entities (parameters, molecule amounts, containers, reactions) in a model structure are accessed by their path. A path is a string that describes the location of an entity in the model structure hierarchy. The path elements are separated by the pipe character `|`. A path can be specified as either an absolute path or a relative path. * An **absolute path** specifies the complete path to a referenced object, e.g., `Organism|Bone|Volume`. An alias defined by an absolute path reference will always refer to the same object, regardless of where the formula is used. * A **relative path** reference specifies the location of the entity *relative* to the location of the formula. The expression `..` is used for "one level up", using a structure similar to that of file systems paths. An example for such a relative reference would be `..|..|Volume`. ### Keywords A reference path may contain generic keywords that are written in `CAPITAL` letters. The following keywords are supported: * `TIME`: The simulation time. Can be used everywhere in a formula. * `MOLECULE`: The molecule in whose context the formula is used. Can be used in parameters of molecules, transports, and observers. * Example: `Organism|Gallbladder|MOLECULE` in the kinetic equation of a passive transport process will refer to the amount of the molecule for which the particular transport is created. * `SOURCE`: The source container of a transport process. Can be used in parameters of transport processes. * Example: `SOURCE|Volume` in the kinetic equation of a passive transport process will refer to the volume of the source container of the transport process. * `TARGET`: The target container of a transport process. Can be used in parameters of transport processes. * Example: `TARGET|Volume` in the kinetic equation of a passive transport process will refer to the volume of the target container of the transport process. * `NEIGHBORHOOD`: The neighborhood in whose context the formula is used. Can be used in parameters of neighborhoods or transport processes. * Example: `NEIGHBORHOOD|Surface area (plasma/interstitial)` in the kinetic equation of a passive transport process will refer to the surface area of the neighborhood in which the particular transport is created. * `FIRST_NEIGHBOR`: The first container of a neighborhood. * `SECOND_NEIGHBOR`: The second container of a neighborhood. * ``: The syntax for using this keyword is `|||`, where `` and `` are the paths of two containers between which a neighborhood exists. While the `` can be an absolute or a relative path, the `` is always given relative to the first neighbor. This keyword is used to generically define paths to neighborhoods without knowing the actual names of the containers. It is usually used in combination with other keywords and relative paths. * Example: `..||..|..|Interstitial||Surface area` is used in a parameter located in intracellular space of an organ, e.g., `Organism|Kidney|Intracellular|ParameterA`. This path points to a neighborhood between the organ's intracellular and interstitial space of the organ. In detail: * The expression before the first `` keyword is `..` and goes one level up and specifies the first neighbor of the neighborhood, e.g., `Organism|Kidney|Intracellular`. * The expression after the first `` is `..|..|Interstitial` and defines the second neighbor. It goes down to the organ level, e.g., `Organism|Kidney` and into the `Interstitial` container, evaluating to `Organism|Kidney|Interstitial`. * The second `` marks the end of the neighborhood path. * `REALIZATION`: An active transport can translate in 1 or more transport realizations (highlighted part below). Realizations could have own parameters which can be referenced using this keyword. ![Active Transport with Realizations](/files/H6bnD5xAuC9s6zXDUpY4) * `TRANSPORTER`: Transporter molecule in an active transport process. * `TRANSPORT`: Reference to the global transport process. Can be used to retrieve global parameters of the transport process. * `ALL_FLOATING_MOLECULES`: String representing a reference to all floating molecules. The entry will be duplicated. This is typically used in event assignment to change all floating molecules at once. * `LUMEN_SEGMENT`: Search for a compartment with the same name as the last part preceding the keyword under Lumen. E.g., for a parameter defined in `Organism|SmallIntestine|Duodenum`, the path `..|LUMEN_SEGMENT|Volume` will resolve to `Organism|SmallIntestine|Lumen|Duodenum|Volume`. * `LUMEN_NEXT_SEGMENT`: Search for the next segment in lumen. Assuming the formula is used in a parameter in `Organism|Lumen|Caecum`, the path `..|LUMEN_NEXT_SEGMENT|P1` will be resolved to `Organism|Lumen|ColonAscendens|P1`. This also works with absolute paths: `Organism|Lumen|Stomach|LUMEN_NEXT_SEGMENT|P1` will be resolved to `Organism|Lumen|Duodenum|P1`. * `LUMEN_PREVIOUS_SEGMENT`: Search for the previous segment in lumen. Assuming the formula is used in a parameter in `Organism|Lumen|ColonTransversum`, the path `..|LUMEN_PREVIOUS_SEGMENT|P1` will be resolved to `Organism|Lumen|ColonAscendens|P1`. This also works with absolute paths: `Organism|Lumen|LowerIleum|LUMEN_PREVIOUS_SEGMENT|P1` will be resolved to `Organism|Lumen|UpperIleum|P1`. # Simulations This section describes the workflows of setting up and running a simulation. There are three ways to set up a simulation in MoBi: * Export a simulation from [PK-Sim to MoBi](/working-with-pk-sim/pk-sim-documentation/importing-exporting-project-data-models#send-to-mobi). * Load a simulation from a pkml file into the MoBi® project. * Create a new simulation from existing modules. ## Load a Simulation A simulation created in PK-Sim or MoBi can be saved as a `*.pkml` file and later loaded into a MoBi® project. * Clicking on the **Load Simulation into Project** button in the Import Ribbon Group. * Right-click on the "Simulations" entry in the Simulations Explorer and select "Load Simulation..." in the context menu. The behavior will be slightly different based on the loaded simulation type. * When sending a simulation from PK-Sim, a new MoBi project will be created. The simulation will be transferred with the observed data sets linked in the simulation. A PK-Sim module (see [PK-Sim modules](/working-with-mobi/mobi-documentation/modularization-concept#pk-sim-modules)) will be created alongside with one individual and the expression profiles used in the simulation. * When loading a simulation from a pkml file that was saved from PK-Sim, a new PK-Sim module will be created alongside with one individual and the expression profiles used in the simulation. If a module, an individual, or an expression profile with the same name already exists in the project, the new modules/individuals/expression profiles will be added as copies with a counter suffix. * When loading a simulation created with OSPS versions prior to 12.0, one module will be created containing all building blocks used in the simulation. * When loading a simulation consisting of several modules, all modules will be created in the project. If a module with the same name already exists in the project, the new module will be added as a copy with a counter suffix. ## Create a Simulation A simulation can be created from at least one module or a combination of modules, individuals, and expression profiles. A specific combination of modules is called **model configuration**. To create a simulation: * Click on the **Simulation** button in the **Create** group of the **Modelling** ribbon. * Right-clicking on the "Simulations" entry in the Simulations Explorer and select "Create Simulation..." in the context menu. A **Simulation Creation Wizard** opens that allows to select the modules, individual, expression profiles, initial conditions, and parameter values building blocks to create the simulation from as depicted below. ![Simulation Creation Wizard](/files/rEStAKFElDee0hOJif1x) In the first step, select the modules that should be combined to the simulation. The selection of the modules results in a *hierarchy* of the modules, where the order of module selection determines the order of overwrite/extend actions. I.e., module 2 overwrites/extends module 1, module 3 overwrites/extends the combination of modules 1 and 2, and so on. For each selected module that contains at least one Initial Conditions or Parameter Values building block, you can select one (or none) Initial Conditions and/or Parameter Values building block. In the next step, select the individual that should be used in the simulation and the expression profiles. Parameters from the individual BB will be added to the simulation structure. {% hint style="warning" %} Selected expression profiles will **not** add a protein that is not present in the model structure! {% endhint %} ![Simulation Creation Wizard](/files/rEStAKFElDee0hOJif1x) During simulation creation, you can enable the checkbox "Create a process rate parameter for each process in the simulation." This will create a parameter called `ProcessRate` for each instance of a reaction or a (passive and active) transport in the simulation. The `ProcessRate` parameter can be used as output and help to analyze and debug the model. {% hint style="info" %} Create of process rate parameter for all processes negatively impacts the performance of the simulation and should only be used for debugging purposes. {% endhint %} Finish the simulation creation by clicking on **OK** . MoBi® now generates the new simulation, the progress of which is visualized by a progress bar. During this process the simulation is also checked for consistency, and possible issues will be reported. ### Warnings and Errors If the simulation creation process detects inconsistencies in the creation process, they will be displayed either as **Warnings** or **Errors** depending on their severity. Errors and warning messages are shown in a notification viewer at the bottom of the page similar to the history viewer. Warnings and error notifications are described in more detail in the viewer as such describing * the origin of the message * the warning text * the warning type The list of warnings and errors is constantly updated, i.e. if a warning is resolved, the entry is removed from the list. Likewise the viewer can be hidden or shown by pressing the **Notification** button in the *Views* section of the *Building block* section of the page. #### Warning: Non-fatal inconsistency. Warnings are generated, for example, in these cases: * References in formulas for non-essential objects like observers are faulty. In this case, the affected observer is simply omitted in the created simulation. * An error in the dimension of a formula, if the option Validate Dimension is selected in Options/User Settings/General (which is the MoBi® default). * An empty condition is present in an event. #### Error: Fatal inconsistency. In this case, the simulation cannot be created. Errors are generated, for example, in case of: * Missing or wrong references in formulas for essential objects like Molecule Start Values. * General syntax errors in formulas. You can choose if only errors, only warnings or both are displayed by clicking (activating/deactivating) the Errors and Warnings buttons in the top row of the Notifications window. Warnings are grouped according to their category. ![Notifications View: Warnings](/files/-LOWQ5Ip1dcHYqbTliKG) The Warnings and Errors displayed in the Notifications View can also be saved in a Log file (csv format) using the **Save Log...** button. You may apply changes and selections to the Notifications table as for any table, see Shared Tools - Features of *Tables*, which can be helpful for longer lists. A double-click on the error message or the warning directly opens the editor in the corresponding building block. ## Defining simulation time - Output Intervals The simulation time is specified in the **Simulation Settings -> Output Intervals** entry of the simulations "Parameters" tree view. Output Intervals specify the simulation times at which simulation results are stored. In MoBi® you can specify a variable number of Output Intervals (as depicted below). Each Output Interval is defined by the following options: | | | | --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- | | **Start Time**: | Starting time of the Output Interval. | | **End Time**: | End time of the Output Interval. | | **Resolution**: | Defines the resolution with which simulation results are displayed and stored. A higher resolution increases the smoothness of the plotted curve. | Each set of options defines a *separate* simulation Output Interval $$\[t\_{start}, t\_{end}]$$ with the corresponding number of output time points $$N\_{t} = \frac{t\_{end} - t\_{start}}{resolution} + 1$$ Additional output intervals can be defined and added to the list by clicking on the ![Image](/files/-LNl8RByZbYsQsNb5Xvn) **Add** button to the right of the list. {% hint style="info" %} * Output Intervals can be overlapping. * The *total* time of simulation is from t = 0 to the highest specified **End Time**. {% endhint %} When creating a simulation, the output intervals defined in the [**Default Simulation Settings**](#default-simulation-settings) are automatically applied. To set the output intervals of a simulation as the project defaults, right-click on the "Simulation Settings" entry of the expanded simulation, select "Make project defaults" and then "Output Intervals and Solver Settings". ![Make Project Defaults](/files/cAxKkM6iU0gmxu1LPOi6) ## Output selections To select the outputs that will be available for plots after a successful simulation run, click on **Define Settings and Run** button in the **Simulation** group of the **Run & Analyze** ribbon. By default, the outputs defined in the [**Default Simulation Settings**](#default-simulation-settings) are automatically applied. To make the current selection of outputs the project defaults, click on "Make defaults" in the output selection dialog, or right-click on the "Simulation Settings" entry of the expanded simulation, select "Make project defaults" and then "Output Selections". In the output selection dialog, only *Observers* and *molecule amounts* can be selected. If you want to plot any of the parameters of the simulation, navigate to the respective parameter in the "Parameters" view of the simulation and enable the "Plot parameter" checkbox. ## Running simulations To run a simulation, open a simulation by clicking on it in the Simulation Explorer. Now you can run the simulation by one of the following options: * Click the **Run** button in the **Simulation** group of the **Run & Analyze** ribbon. * Press the function key **F5** Alternatively, select the **Run** option within the simulation context menu (opens when right-clicking on the simulation in the **Simulation Explorer** ). The progress of a simulation run is shown by the progress bar in the lower right corner of the MoBi® window. A running simulation can be stopped by clicking the **Stop** button in the Simulation Ribbon Group which will become active during a run. The results of all simulation runs are accessible through the Simulation Explorer and the edit window. After a successful simulation run, the most recent results can be displayed in the **Results** tab in the simulation edit mode as described in MoBi® *- Simulation Results*. ## ODE Solver Properties MoBi® uses the CVODE differential equation solver. The solver settings can be accessed and edited in the simulation edit mode in the "Simulation Settings -> Solver Settings" node. {% hint style="warning" %} For more information on the solver, please refer to the documentation of the CVODE solver: . {% endhint %} The following options can be changed by the user: | | | | ------ | -------------------------------------------------------------------------------------------------- | | MxStep | Maximum number of internal steps to be taken by the solver in the attempt calculate one time step. | {% hint style="info" %} For some "difficult" problems, the predefined value of MxStep might be too small. In case of such difficulties, try to increase the value of MxStep. {% endhint %} | | | | ------ | -------------------------------------------------------------------------------------------------------------------------------------- | | H0 | Initial step size. | | Hmin | Minimum absolute value of step size allowed. Increasing Hmin may speed up the simulation but also reduces the accuracy of the solver. | | Hmax | Maximum absolute value of step size allowed. Reducing Hmax may slow down the simulation but also increases the accuracy of the solver. | | AbsTol | Absolute tolerance of solver accuracy. | | RelTol | Relative tolerance of solver accuracy. | The parameters RelTol and AbsTol define a vector of error weights, ewt, defined as: $$\text{ewt}\[i] = \frac{1}{\text{RelTol} \times | y\[i] + \text{AbsTol}|}$$ where $$y$$ is a variable vector $$y = f(t)$$. This vector is used in all error and convergence tests, which use a weighted root mean square (RMS) norm on all error-like vectors $$v$$: $$\text{WRMSNorm}(v) = \sqrt{\frac{1}{N} \sum\_{i=1}^{N} (v\[i] \times \text{ewt}\[i])^2}$$ where N is the length of vector $$v$$. | | | | ----------- | --------------------------------------------------------------------------------------------------------------------------------------------- | | UseJacobian | If the Jacobian matrix of the ODE system should be supplied to the solver, use the value 'True'. Using the Jacobian speeds up the simulation. | {% hint style="warning" %} Setting tolerances higher than the default values (absolute tolerance: 1.0E-10; relative tolerance: 1.0E-5) may reduce simulation time but cause convergence errors. However, when scale divisors are calculated and applied to a simulation, solver tolerances can often be safely increased without compromising accuracy. See [Calculate Scale Divisors](#calculate-scale-divisors) for more information on scale divisors. {% endhint %} ## Default Simulation settings The project defaults for simulation output intervals, output selections, and solver settings can be defined in the **Default Simulation Settings** accessible through the **Edit** button of the **Simulation Settings** group in the **Modelling** ribbon. When a new simulation is created, these default settings are automatically applied. The default simulation settings can be exchanged between projects by saving them to and loading from a pkml file. The following defaults can be defined: * **Output Intervals**: start and end time point of a simulation and resolution of a simulation. * **Solver Settings**: solver parameters such as the tolerances. * **Output Selection**: outputs that will be available for plots. The outputs are represented as the paths to the observers that can be selected in the simulations. ![Default Simulation Settings - Output Selection](/files/iOpxaeOPK3ZjdTKF05ZP) The user can manually change the path, or select an observer from any simulation in the project by clicking on "...". New outputs can be added by clicking on the "+" sign. {% hint style="info" %} The outputs defined in this view will be automatically applied to new simulations created in the project. If a simulation does not contain an observer defined in the default output selection, the output will be ignored for that simulation. {% endhint %} * Chart Templates: a set of chart templates can be managed in the **Chart Editor**. ## Editing Simulations Once a simulation is created, the basic structure of the simulation model is fixed. In a simulation, you can only change the values of parameters and initial conditions of molecules. Also, if the value of a parameter is defined by an explicit formula you can only edit the numeric value of the formula, but not the formula definition. This means, that for example the kinetic formula of a reaction or the formula used for a certain observer are no longer editable. They may only be changed by changing a parameter the used formula depends on. All changes made to the parameter or initial condition values are listed in the tab **Changes** of the simulation edit mode. {% hint style="info" %} It is recommended to select all parameters under consideration as **Favorites** and to document the source of all parameter values changed from the default in the column **Value Description**. Then you have a comprehensive overview about the essential input of your simulation, which you can document by copying just the Favorites table. {% endhint %} {% hint style="warning" %} If you change the value of a parameter defined by an explicit formula, the Formula Type will switch to *Constant* and the parameter is no longer dependent on the specified formula, but stays on the newly specified numeric value. {% endhint %} {% hint style="info" %} After changing a parameter value, the parameter can be reset to its original value by clicking on the icon **Reset Parameter to default** , which appears after changing a value. (If a formula dependency of a parameter is overwritten by changing the parameter value, a yellow warning sign appears. {% endhint %} {% hint style="info" %} If you need to change formulas, edit the corresponding building block and create a new simulation instead of editing the simulation. In the following sections, a brief overview is given on where you can find the parameters that are specified in the building blocks from which the simulation was created. The examples given in some cases refer to a standard PK-Sim® simulation which was exported to MoBi®. {% endhint %} ### Container and Neighborhood Properties The container parameters are located at the same level where they were originally defined in the Spatial Structures building block, e.g., accessible by double- clicking the "Plasma" container at the "Organism|Liver" level. Parameters associated with Neighborhoods, e.g., "Surface Permeability Area", are also located at the same level on which they were originally defined in the Spatial Structures building block. For the kidney, for example, "Surface (Permeability) area" can be found under `Neighborhoods|Kidney\_int\_Kidney\_cell`. ### Molecular Properties Molecules can have either **global** or **local** parameters. | | | | ------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Global | The parameter is attached to the respective molecule at the first level of your Simulation Hierarchy tree. | | Local | The parameter is attached to the respective molecule where it is located in a physical container, e.g., accessible by double- clicking on a molecule located at the `Organism\|Liver\|Plasma` level of your Simulation Hierarchy tree. | Parameters of active transports are defined as a sub-node of the molecule that is transported. Parameters of protein interactions are defined as a sub-node of the molecule that is interacting with the protein. ### Reaction Kinetics Parameters associated with reactions can also be local or global. Thus, the same rules as for molecule parameters apply also to reaction parameters as specified above. ### Passive transports Parameters of Passive Transports are located in the neighborhoods where the respective passive transport is created. ### Event and Application Properties Parameters associated with Event and Application Properties can be accessed at the root level of the simulation hierarchy tree within the **Events** node. They are located at the same relative location as the Events building block from which the simulation was created. ## Update and Commit Changes Between Simulations and Modules. Within the **Simulation Explorer**, each building block item of the **Configuration** tree is displayed with a green or red traffic light. The traffic lights indicate if the building block item of the simulation is consistent with the corresponding general **Building Block**. If a **Building Block** or parameter settings within a **Simulation** are changed, the red traffic lights in the **Simulation** window indicate that the local settings in the simulation are different from the settings in the general **Building Block**. A right click on the red traffic lights in the **Simulation** window allows for two actions: ![Image](/files/-LOWQ5JZQNYGit0ktQh_) ### Update from building blocks If the information in the building blocks differs from that in the simulation, the simulation can be recreated using the same model configuration by right-clicking on the simulation and selecting **Update from Building Blocks**. This action is identical to creating a new simulation from the same model configuration. All local changes in the simulation will be lost. ### Commit to building blocks Changes in parameter or initial condition values can be propagated to the modules. {% hint style="warning" %} Structural changes cannot be propagated to the modules. For example, if a reaction is added in the building block of a module, commiting from the simulation to the module will not remove the reaction. {% endhint %} Right-click on the simulation and select **Commit to Building Block**. A dialog opens that allows to select which changes should be committed to the building block. The values are always committed to the **selected** parameter values or initial conditions building blocks of the **last module** used in simulation configuration. If no Parameter Values or Initial Conditions building block is selected for the last module, a new building block is created. ## Further Options for Simulations Once a simulation is created, a number of options besides simply running the simulation are available. ### Calculate Scale Divisors Internally, very small numerical values are divided by the scale divisors to get to an order of magnitude which is reasonable for the solver. The purpose is to reduce numerical noise and to enhance computation performance. This is also important when working with a broad variety of magnitudes of values. The scale divisors specify a typical scale for each species. Per default, all scale divisors are set to 1. If you work with very small amounts and/or a broad variety of magnitudes of values and your simulation yields implausible results (numerical noise, negative values, etc.), use the **Calculate Scale Divisor** function located in the **Simulation** group of the **Run & Analyze** ribbon to adjust the scale divisor for computational purposes. ### Context menu The context menu that opens when right-clicking on the **Simulations** node in the Simulation Explorer offers the following options: * **Create Simulation** - opens the Simulation Creation Wizard (see [Create a Simulation](#create-a-simulation)). * **Load Simulation** - loads a new simulation into the project (see [Load a Simulation](#load-a-simulation)). * **Create Subfolder** - creates a new subfolder in the Simulations Explorer to organize simulations. * **Delete all subfolders and keep data** - deletes all subfolders in the Simulations Explorer, but keeps the simulations contained in the subfolders in the main Simulations Explorer. * **Delete all subfolders and data** - deletes all subfolders in the Simulations Explorer, including all simulations contained in the subfolders. * **Delete all results** - deletes all simulation results of all simulations in the project. The context menu that opens when right-clicking on a simulation offers the following options: * **Edit** - opens the simulation in the edit window (same as double-clicking). * **Rename** - renames the simulation. * **Configure** - opens the Simulation Creation Wizard to change the model configuration of the simulation. All local changes in the simulation will be lost. * **Update from Building Blocks** - updates the simulation from the building blocks used in the model configuration. All local changes in the simulation will be lost. * **Run** - runs the simulation. * **Stop** - stops a running simulation. * **Start Parameter Identification** - calls Parameter Identification tool (see [Parameter Identification](/shared-tools-and-example-workflows/parameter-identification) for description). * **Start sensitivity analysis** - calls Sensitivity Analysis tool (see [Sensitivity Analysis](/shared-tools-and-example-workflows/sensitivity-analysis) for description). * **Send to PK-Sim for Population Simulation** - sends the simulation to PK-Sim® and opens PK-Sim®. The simulation can then be used as basis for a population simulation in PK-Sim® (see [Running and analyzing a population simulation](/working-with-pk-sim/pk-sim-documentation/pk-sim-creating-populations) for description). * **Save Simulation to MoBi pkml format** - saves the simulation as pkml file. * **Add to Journal** - adds a snapshot of the simulation to the Working Journal (see [Working Journal](/shared-tools-and-example-workflows/working-journal) for description). * **Export results to Excel®** - generates an MS Excel® output file containing all result data (see [Simulation Results](/working-with-mobi/mobi-documentation/simulation-results)). * **Export Simulation as Matlab® Differential Equations** ... - exports the system of ordinary differential equations (ODE) of the simulation to m-files for MATLAB®. Into the output directory defined, several m-files defining the ODE system are written. The most important files are: * *ODEMain.m*. This is the main function. Calling this function from the MATLAB® command window by typing *tout, yout = ODEMain* will provide the numerical solution to the ODE system, whereby *tout* is the time- point vector and *yout* the solution matrix, containing the time-dependent changes of the modeled species. The matrix entry ordering is as specified and explained in the file *ODEInitialValues.m*. * *ODERHSFunction.m*. This file contains both the parameters and the differential equation definitions. Parameters are transformed from a hierarchical structure used in MoBi® to a flat structure used in MATLAB®. Therefore a renaming is necessary to P\_number using a consecutive numbering. The hierarchical MoBi® correspondence is provided as a commentary. * *ODEInitialValues.m*. This file specifies the initial conditions. The hierarchical species names of MoBi® are transformed into vectors in MATLAB®. The MATLAB® commentary provides information on the MoBi® species - vector relationship. * *ODEoptions.m*. This file contains numerical settings as chosen in MoBi®. The ode15s solver is used within MATLAB® (cf. *ODEMain.m*) . Please consult the MATLAB® help for additional information. * **Create simulation report** - generates a plain text (txt) file containing all simulation information. * **Export Model as Tables** - exports Reactions, Parameters Values and Initial Conditions into separate worksheets of an Excel® file. * **Import Simulation Parameters** - Import parameter values from an Excel®. See [Parameter Values Building Block](/working-with-mobi/mobi-documentation/parameter-values-bb) for details on the required structure. * **Clone** - Create a copy of the simulation in the project. * **Delete** - deletes the simulation from the project. * **Delete all results** - deletes all simulation results of the selected simulation. # Simulation Results Simulation results are stored during a simulation when observers are defined as described in “Observers”. The results are available for display once an existing simulation has been run. The simulation results of a simulation are listed in the simulation explorer tree below the corresponding simulation. To display the simulation results, either double-click on the results or right-click on them and select **Show Data** in the context menu. The results can then be accessed in a new tab in the main window. The most recent results are also shown in the "Results" tab which can be accessed in the simulation edit mode. To display the simulation results in a chart window use the Chart Editor as described in detail in [Shared Tools - Chart Component](/shared-tools-and-example-workflows/chart-component). {% hint style="info" %} Results of different simulations can be displayed in the same chart. Simply drag\&drop a simulation result node from the Simulation Explorer into an existing chart. The corresponding repository is displayed in the data browser. For better overview you can select the column Repository in the data browser table using the **Column Chooser**. Then you can select data from both result repositories for display. {% endhint %} ## Observed Data To compare the simulation results with observed (i.e., experimental) data, e.g., measurements of blood plasma concentrations, the Open Systems Pharmacology Suite comes with a powerful tool for importing observed data which is described in [Import and Edit of Observed Data](/shared-tools-and-example-workflows/import-edit-observed-data), which is also available in MoBi®. ### Importing Observed Data To import observed data either use the **Observed Data** button in the "Modeling\&Simulation" ribbon group "Import" or right-click on the **Observed Data** building block in the Building Block Explorer and select **Import Observed Data from Excel** in the context menu. MoBi® supports the import of MS Excel® worksheets in a defined format which is also described in detail in [Shared Tools: Import and Edit of Observed Data](/shared-tools-and-example-workflows/import-edit-observed-data). Once the import has been completed, the imported data are added to the "Observed Data" building block in the Building Block Explorer. The building block that contains the observed data may be renamed by right-clicking on it and selecting Rename in the context menu. ### Display Observed Data The imported datasets can be displayed either in a new chart or within an existing chart. To display the data in a new chart right-click on the data and select **Show Data** in the context menu. To display the dataset in an existing chart window, simply drag\&drop the dataset into the chart. The observed dataset is then also listed in the data browser of the chart editor. ### Deleting imported Observed Data To delete imported observed data from the project right-click on the data and select Image **Remove** in the context menu (or simply press the **Delete** key on your keyboard to delete the selected data). This also removes the data from the chart and the data browser of the chart editor. ## Exporting Simulation Results and Parts of a Simulation Model MoBi® supports the export of simulation results to MS Excel® as xls or xlsx spreadsheets as well as the export of an image of the chart. ### Export Data To export simulation results, right-click on the simulation in the simulation explorer and select **Export results to Excel** in the context menu. {% hint style="warning" %} All existing results of the selected simulation are exported! In case the simulation produces a large number of results (high number of compartments, molecules, or observers), you may reach the limit of MS Excel® file size. {% endhint %} MS Excel® is automatically started and new worksheets, one for each simulation, are created. ### Export an Image of a Chart Charts can be exported by copying an image of the chart to the clipboard: * Right-click on the chart and select **Copy as Image** * Press **Ctrl+C** when viewing the chart Then change to an image processing program and insert the image of the chart using the paste function. MS Windows® standard for this operation is **Ctrl+V**. ### Export Parts of a Simulation Model Specific parts of a model can be exported as editable list into xls format. The export is done per simulation and initiated by context menu in the simulation explorer. Upon initiation of the export, the user has to specify the path for import and either use the suggested file name or else override it. The exported parts comprise reactions, molecules and parameters that will be exported into one sheet each in the export file. ![Export of the simulation parts reactions, molecules and parameters as processable list is initated in the context menu](/files/-LNl8Q5S1U-J-mGjzzMf) # Diagrams Overview In this chapter you find an overview and details of the diagrams usage. For the three building blocks **Reactions**, **Spatial Structure**, and **Simulation**, diagrams (also known as flow charts) are available in addition to the structure by lists or trees for the following reasons: * Reactions and molecules form networks, which are much easier to comprehend from a graphical representation. * The spatial structure consists of hierarchical containers, which are connected by so called neighborhoods; a two dimensional diagram can represent the structure much more naturally than a one dimensional list or tree. * The simulation is built from a spatial structure and reaction networks within each compartment; so here the most complex graphical representation is required. These diagrams are used for three purposes: visualization, navigation and editing of complex models. In the following sections we will first describe these general concepts and features (using examples from a Spatial Structure diagram), and then the features specific for the different building block diagrams. ## General Visualization, Scrolling and Zooming Obviously, you can comprehend two-dimensional network structures much easier in appropriate graphical representation. The most common example is an organism model exported from PK-Sim® to MoBi®, but you may also have simpler spatial structures (see “Spatial Structures” for an example). You may zoom and scroll within the diagram, if the whole model cannot be displayed at once. To scroll the diagram, use one of the following options: * Use the scrollbars. * Use the mouse wheel to scroll vertically or press the **Shift** key while using the mouse wheel to scroll horizontally. * For the spatial structure and simulation, there is a **Diagram Overview** to the left of the diagram and above the model tree. Here, the current clipping is marked by a rectangular frame. You can pick this frame at its edge and move it to select the displayed clipping of the diagram, i.e., to scroll the diagram. Image To zoom the diagram, use one of the following options: * Press the **Ctrl** key and use the mouse wheel to zoom in and out. * Press the **Shift** key and drag the mouse to select a rectangle to zoom into the selected area. * Right-click in the diagram to open the **context menu** and select a zoom command from the submenu **Diagram**. * In the **Diagram Overview** (see above), use the mouse to grab the frame at the corner and resize it to zoom the diagram. ![Image](/files/-LNl8SGShmUUD-nhh0vI) ![Spatial Structure Visualization](/files/-LNl8SGUNLcZVE9XcEIs) For visualization, model containers are represented by **container nodes**, which can be expanded and collapsed (see next section). Other model entities are represented by **elementary nodes** and **links**. Neighborhoods, for example, are represented by a neighborhood node and links. ## General Navigation, Expand and Collapse You do not want to remain a passive viewer of these pictures, instead you want to use the graphical representation for navigation within the model and even for editing the model. Of course, the navigation by the diagram and list or tree view is synchronized. You can navigate to some entity in the tree view or list and when you double click it, the diagram view is adjusted to show this entity and the **Properties Editor** opens. Alternatively, you can navigate to some entity in the diagram, double click it, and the list or tree view is adjusted to show the entity and the properties editor opens. In the spatial structure and simulation view, you can navigate into subcontainers and return to the parent container by expanding and collapsing a container. Do one of the following: * Click the **expand** symbol ![Image](/files/-LNl8SGdZqhjlDHfOOPU) in the top left corner of a container to expand the container. Except for the parent containers, the superstructure is often masked out for clarity. * Click the **collapse** symbol ![Image](/files/-LNl8SGbbvIv1gsntAuW) to collapse a container. A possibly hidden superstructure is redisplayed. * At anytime you can right-click into the diagram to open the context menu and select **Show all children** to show all hidden children of a container. * Press **Shift** and click ![Image](/files/-LNl8SGdZqhjlDHfOOPU) to expand a container without hiding other containers. * Press **Shift** and click ![Image](/files/-LNl8SGbbvIv1gsntAuW) to collapse a container without redisplaying hidden structures. * Press **Ctrl** and click ![Image](/files/-LNl8SGdZqhjlDHfOOPU) / ![Image](/files/-LNl8SGbbvIv1gsntAuW) to expand resp. collapse a container recursively. ![Expanded Kidney Structure](/files/-LNl8SGhT-x_vql7CbHA) ## General Editing Editing is a more complex topic than navigating. You can make three kinds of changes: * Model changes by adding or removing entities * Diagram changes for example by changing or fixing the location of nodes * Display changes like zooming and scrolling and Diagram options The model and diagram state after changes is stored within the project, diagram options are stored within the user settings, zooming and scrolling is not stored. You can perform many changes via the context menu. To open the **context menu**, right-click somewhere into the diagram. Depending on the location context, different menu items are displayed. The following context menu is shown when you right-click on a container. ![Container context menu](/files/-LNl8SGjc7ZVmtr1ovek) The different context menu items are described in the sections below. #### Model Changes To edit the model, do one of the following: * Select **Create Container** from the **context menu** to add a new container (or any other entity type). * Select **Load Container** to load a previously saved container (or any other entity type). * Select **Rename** to rename an entity. * Double click the entity or select **Edit** from the context menu to focus and edit an entity. * Select **Save** to save an entity separate from the project. You can load such entities in the same or into other projects. * Select **Remove** to remove an entity. ### Diagram Changes You can rearrange the position of nodes or hide nodes in order to get a better visualization in general or for publishing (you can export diagrams as bitmaps, see [More Actions](#more-actions)). #### Selection of Nodes First select a single diagram node or a collection of diagram nodes you want to change. Do one of the following: * Click a node to select it. * Press the **Ctrl** key and click a node to add it to the selection * Press the **Ctrl** key and drag a rectangle to add all nodes inside the rectangle to the selection * Select **Select / All Children** from the **context menu** to select all children of a container. * Select **Select / Visible linked nodes** to select all visible nodes, which are linked to nodes in the current selection. * Select **Select / Invert selection** to invert the selection within a container. #### Basic Actions Now you can move, hide or resize the selected nodes: * Drag the mouse to move the selected nodes. After moving a container, its neighborhood node positions are automatically adjusted. * Select **Diagram / Location fixed** from the **context menu** to fix the location of selected nodes and prevent them from automatic movement (neighborhood node adjustment or Auto layout). You can deselect the checkbox, if you want to re-enable automatic movement. * Select **Hide Selection** to hide the selected nodes. * Select **Show all children** to show all hidden children of a container. * If your collection contains not only container nodes but also elementary nodes, you can select **Large**, **Middle**, **Small** from the submenu **Nodesize** to change the node size of selected element nodes (neighborhoods, molecules, reactions, observers). {% hint style="info" %} You may use different node sizes to emphasize important reactions and molecules or to minimize marginal reactions or molecules. {% endhint %} * Select **Undo Diagram Layout change** to undo diagram changes like collapse/expand or auto layout. Model changes break the undo sequence, and also hide/show cannot be undone. Observe that the **History Manager** only stores model changes but not diagram changes. * Select **Diagram / To front** or **Diagram / To back** to bring an element into front resp. back of another element/container in case of overlapping of containers and other nodes. * Select **Refresh** to refresh a diagram, for example after changing the Diagram Options (see [Display Changes](#display-changes)). #### Layout Actions Instead of laying out the diagram by these basic actions you can also lay out the selected containers by using **diagram templates** or **auto layout algorithms**. Auto layout of nodes via forces (repulsion by electrical charges, attraction by springs) is generally available, but yields inferior results in case of complex node networks. In the **Reaction** diagram, the context menu item "Auto layout in layers" yields good results in most cases, so using this function is recommended here. The first template is often already used. When opening a Spatial Structure for an organism without diagram information (e.g., from PK-Sim®), a SpaceOrganismTemplate.mbdt is used - from the corresponding users profile (default path is C:\Users\\\AppData\Roaming\Open Systems Pharmacology\MoBi\3.0), if available, or else from the MoBi® installation folder. Here are two tips, how you can benefit from templates: {% hint style="info" %} You may define your own default organism template. For this purpose, save the organism container that you have modified according to your needs at the above location as SpaceOrganismTemplate.mbdt. (Saving templates is described below). {% endhint %} {% hint style="info" %} You can layout an organ in a simulation with all compartments expanded and reaction and transport networks arranged. Then save this organ container as template and apply this template to a selection of other organs. {% endhint %} To use a container template for layout: 1. Layout a container manually as described in the previous section. 2. Right-click in this container and select **Layout / Save Container as named Template** from the **context menu** to save the diagram information of the container and all contained elements as a template. 3. Select one or more containers, which you want to layout with this template. 4. Right-click on one of these containers and select **Layout / Apply named Template to Selection** to apply the container template to the selected containers. The diagram settings from the template and its contents will be transferred to the selected containers; the children are identified by their path. In case of missing information in the template the respective element remains unchanged. In case of template elements not available in the container nothing happens. {% hint style="warning" %} You can use spatial structure templates for a simulation, but not vice versa. {% endhint %} In addition, you may use the following features: * To save and load a diagram template, select the analogous items from the diagram context menu (right-click on the diagram pane). * Select **Layout / Apply named Template to Container recursive** to apply a template to a container recursively; that means the template is applied to each subcontainer of the container. For example you can apply an organ template to all organs inside an organism by selecting this context menu item at the Organism container. * Select **Layout / AutoLayout children** to apply a force-based auto layout. #### More Actions You can export a container as bitmap: * Select **Diagram / Copy as bitmap** from the container or diagram context menu to copy the selected container or diagram as bitmap into the clipboard, from which you can insert it into documents or slides. * Select **Diagram / Save as bitmap** from the container or diagram context menu to save the selected container or diagram as bitmap to a file. ### Display Changes We have already explained in “General Visualization, Scrolling and Zooming” how to change the display of a diagram by zooming and scrolling. You can change the general appearance of the diagrams in the **Diagram Options** tab within the **User Settings** dialog (click **Options** in the Utilities ribbon tab). All these options are stored in the user settings and apply to newly opened diagram tabs. Refresh a diagram to apply the diagram options to an existing diagram tab (see “Basic Actions”). The default node sizes apply only to newly created elementary nodes, because current node sizes may have already been changed by the user. Here you can change the **diagram colors** for nodes and links. You can change the **default node size** for reaction, molecule and observer nodes. You can show or hide * the snap grid of the diagram pane, * the molecule properties container in the spatial structure and simulation diagram, * the observer links in the simulation diagram, * Molecule nodes, which are unused in the simulation diagram containers. ## Reactions Diagram ### Visualization The Reaction building block consists of a list of reactions. Each reaction has educts and products, which are listed in the stoichiometry tab of the reaction properties editor. In the reactions diagram the reaction is represented by a triangle with a blue educts port, a green products port and a red modifiers port. Modifiers are molecules which influence the reaction, but which are neither consumed nor produced, e.g., enzymes. Modifiers, like educts and products, are listed in the properties tab of the reaction properties editor, so they can be used within formulas. Besides these reaction nodes, the reaction diagram can contain molecule nodes. The molecule nodes themselves do not represent any model objects (neither from the reactions building block nor from the molecules building block), they only represent molecule names. Instead, an educt is represented by the connection between the educts port of a reaction node and a molecule node with the educt name. Products and modifiers are represented analogously by connections to the corresponding ports. ![Example Reaction Diagram](/files/-LNl8SHDEfRdTr96urOv) In the reaction diagram, no containers are used, so the remarks from “General Navigation, Expand and Collapse” do not apply here. {% hint style="info" %} The diagram colors can be changed in the diagram options (see [Display Changes](#display-changes)). {% endhint %} ### Model Changes You can **insert reactions and molecule nodes** by the context menu as described in “Model Changes”. To **add an educt, product or modifier to a reaction**, connect a molecule node with its name to the corresponding port of the reaction node by doing one of the following: 1. Move the mouse to the outer circle or the molecule node until the mouse pointer looks like ![Image](/files/-LNl8Qfl6F1gz0eB0LdL); now you are in connection mode. 2. Click and hold the left mouse button and drag the mouse to the intended port. A straight connection line is shown during dragging the mouse. 3. When you reach the vicinity of a port, the connection line snaps to that port. Move the mouse to the vicinity of the intended port. 4. Release the mouse button. A colored bended connection line is drawn now. Alternatively, you can establish a connection in the opposite direction: Move the mouse first to the port until you are in connection mode (![Image](/files/-LNl8Qfl6F1gz0eB0LdL)) and connect to a molecule node as described before. To **remove an educt, product or modifier from a reaction**, disconnect the molecule node from the corresponding port of the reaction node by clicking on the connection line (it will then be marked by four squares) and pressing the **Delete** key. In the same way, you can remove an unconnected molecule node by clicking it and then pressing the **Delete** key. ### Diagram Changes To move a molecule or reaction node, move the mouse to the center of the node until the cursor looks like ![Image](/files/-LNl8QfnyMVMrcH1Q7dj) click it and move it around. In circular reaction-molecule networks you may swap the positions of the educts and products port for some reaction nodes. To do so, check **Connect Educts right** in the **context menu** of a reaction node. To apply an auto layout in layers to a reaction diagram, select **AutoLayout in layers**. This auto layout yields good results in most cases. Molecules and reactions are ordered from basic educts on the left to final products on the right. Any swapped ports for educts and products are therefore reset by this action. You can emphasize and minimize reaction and molecule nodes by changing their node size in the context menu. {% hint style="info" %} In more complex reaction-molecule networks, some molecule names may be used in many reactions. In such cases, you may prefer more than one molecule node for this molecule name to avoid long connection lines with many intersections. You can create so called **twin nodes** by inserting a molecule node with the same name. Ports are now connected to the nearest twin node of a molecule name - at least after a **Refresh**. You cannot connect them to a twin node further away. {% endhint %} ## Spatial Structure Diagram Most features of spatial structure diagrams have been explained in the general sections before. To **insert a neighborhood** between two physical containers: 1. Move the mouse to the boundary of one of the physical containers you want to connect by a neighborhood until the cursor looks like ![Image](/files/-LNl8Qfl6F1gz0eB0LdL); now you are in connection mode. 2. Click and hold the left mouse button and drag the mouse to the other physical container. A straight connection line is shown when dragging the mouse. 3. When you reach the vicinity of a physical container, the connection line snaps to that container and turns from a thin red line to a thick black line. Move the mouse to the vicinity of the intended container. 4. Release the mouse. A **New Neighborhood** dialog appears. 5. Enter a unique name and click **OK**. A new neighborhood is generated. ## Simulation Diagram Most features of simulation diagrams have been explained in the general sections before. For the layout of a simulation diagram, you have an additional option. You can layout the underlying spatial structure and reaction diagrams first and then select **Apply current layouts from Structure and Reaction** from the **context menu** to apply that spatial structure layout to the container structure of the simulation diagram and to apply the reaction layout to the reaction-molecule network inside each physical container. If you have opened (and possibly edited) the spatial structure diagram before you have opened the simulation diagram for the first time, the current spatial structure diagram (and the reaction diagram, if applicable) is automatically used as a template. Otherwise, when opening a simulation for an organism without diagram information (e.g., from PK-Sim® ) for the first time, the same SpaceOrganismTemplate.mbdt is used. In the **Diagram Options** of the User Settings ([Display Changes](#display-changes)) you can show or hide * the molecule properties container in the spatial structure and simulation diagram, * the observer links in the simulation diagram, * molecule nodes, which are unused in the simulation diagram containers. # Tools ## Search Function MoBi® contains a powerful search function to find parameters, molecules, reactions, or other elements in a project or simulation. This function is useful to locate parameters or elements of building blocks or simulations (e.g., molecules, parameters, container) within the current project. To perform a search, make sure that the search window at the right side of the MoBi®window is expanded; like the Chart Editor or History window, the Search window can be collapsed by clicking **auto hide** ![Image](/files/-LNl8PnfBnAMbSc04a_n) (see [MoBi® - Window Overview](/working-with-mobi/mobi-documentation/first-steps#mobi---window-overview)) and made again visible by clicking the **Search** bar. If in collapsible mode, the search window can be switched to the permanently visible mode by clicking **dock** ![Image](/files/-LNl8PiV8fj-YvNWI59a). A search text can then be entered into the **Search** input box. This may be the name of an element of a building block or simulation or a part of a description. The scope of the search can be selected in the **Scope** combobox: * Selecting Project will search through the entire project, meaning all contained building blocks and simulations. * Selecting Local will search only within the currently edited building block. * Selecting AllOfSameType will search within the currently edited building block and all other building blocks of the same type. If, for example, you are currently editing a Molecules building block and have several of them in your project, the search will show results from *all* molecules building blocks. Several search options can be selected by checkboxes: * Checking **Match whole word** will only return results where the whole word is matching what is entered in the **Search** input box. * Checking **Use regular expression** will treat the text in the **Search** input box as a Regular Expression in the search. See other references (e.g., ) for the explanation of a Regular Expression if you are not familiar with them. * Checking **Match Case** will only return results where the upper and lower case of the characters entered into the **Search** input box matches. This checkbox cannot be used in combination with **Use regular expression** and will thus become inactivated once you select the previous checkbox. To start the search, click on the magnifier glass icon at the right side of the **Search** input box. The results will then be displayed in the Search Results table; if nothing is found, this list will remain empty. Initially, only the building block names with search hits are listed in the results window, but you can expand the lists by clicking the symbol in front of the name. {% hint style="info" %} Double-clicking a listed item will show it in the edit window where you can view it in detail or enter changes. {% endhint %} ## Project History The history manager allows you to document all steps that lead to a specific project status and particular results in MoBi®. With this manager you will be able to easily step back to previous states of your project work in the current session (i.e. a session endures from start of MoBi® to closing the program). The different lines in the manager represent different steps in modeling in the current project. Here we only give a brief description; for more details see [History Manager and History Reporting](/shared-tools-and-example-workflows/history-manager-history-reporting). {% hint style="info" %} If you want to test different possible directions in modeling of a specific problem, you can use this functionality to step back to the "decision point" (within the current session). {% endhint %} You will be able to reproduce every step that you have made during the project. In the window you will see the number of steps in the column **State After Action**. You can add labels in the history to mark important steps in your project modeling history and comment them by using the **Add Label...** button in the bottom. You can also change these comments by selecting a status in history and click on **Edit Comments...**. The **Rollback...** allows the user to step back to any numbered status in the current session. ![History Manager in MoBi®](/files/-LNl8PiYzudoY0CSE5z6) # Reuse of Project Information from Previous Versions ## Reuse of MoBi® 2 projects in MoBi® 3 MoBi® 2 projects are not supported any more. ## Conversion of MoBi® 3.1 projects. Projects created with MoBi® 3.1 are automatically converted when opened. In MoBi® 3.1 in some cases it was necessary to insert manual conversion factors into formulas, if dimensions with inconsistent base units were used. In the current version such conversion factors are not longer necessary. {% hint style="warning" %} If you have inserted such manual conversion factors, you have to eliminate those factors and to rebuild the simulations to get proper simulation results. Please perform the following steps to identify and remove manual conversion factors and to rebuild the simulations. {% endhint %} 1. Open the project stored from MoBi® 3.1. 2. Open the Notifications view, which is autohidden at the bottom by default. 3. Double click each row with message "Dimension check warning". The corresponding formula is opened. Remove any manual conversion factors (mostly powers of 10), if available. Do not remove other factors. 4. Rebuild each simulation of interest, i.e. build a new simulation with the same building blocks and use the same simulation settings and modifications as in the corresponding old simulation. 5. Run each new simulation and compare the results. In case of differences check the formulas with "Dimension check warning" again. In case you have to adjust a formula rebuild the simulation again. Otherwise compare carefully the used building blocks, simulation settings and simulation parameter modifications. If you still get different results, please contact our support (). 6. If you successfully managed to rebuild the simulations with the same results, remove the old simulations from the project. (Due to the conversion factors still contained in those simulations you would produce wrong results running the old simulations with the new version of MoBi.) # Example Workflows The following workflows illustrate how to use MoBi in different scenarios. ## Modularization use case - adding a tumor to a PBPK model This workflow illustrates how to add a tumor compartment to a PBPK model in MoBi. The steps are as follows: * Export a simulation from PK-Sim to MoBi. This will create a PK-Sim module. ![Image](/files/p4K66ygq1dKCxB57Y7Ip) * Open the spatial structure of the PK-Sim module, select a tissue organ (e.g., muscle), and export it to pkml, e.g. as "**Muscle.pkml**". ![Image](/files/mYlbJK6s0PjG8GUM4T7n) * Optionally, select an individual and expression profile(s) to include in the exported organ. ![Image](/files/y5LUyVw5WNikSlLwy2vU) * Create a new "Tumor" extension module with the "Spatial Structure" and "Initial Conditions" building blocks. ![Image](/files/9X6Oxq7Ht5IjRPnZPRUg) ![Image](/files/8GpTA7IoFSm1cUDLvNuG) * In the "Tumor" extension module: open the spatial structure and load the top container from the previously saved file Muscle.pkml.

Note that the neighborhoods between muscle and arterial/venous blood are also loaded.

![Image](/files/Vq4kTlWQlIGgqy5QVXwt) ![Image](/files/dow0GtZMhLF8LSxYOp9G) * Rename the "Muscle" container to "Tumor". **Be sure to check the "Rename Related Entities" checkbox in the next dialog!**. ![Image](/files/u9xI8oplDeMFLsLJJbvy) ![Image](/files/N38lGjSJBIxtm2o8jrIl)

After renaming, the neighborhoods have been renamed accordingly.

![Image](/files/Lvu5Y0AafqQiJvRXGjZ2) * Open the Initial Conditions building block of the Tumor module and click on "Extend". ![Image](/files/2UlkPIToWtPpdEYZyjMM) * Select molecules to be incorporated into the tumor. ![Image](/files/bQQhg3dojwbh6pxFPRjV) ![Image](/files/z2zQuHQQr9zgQqVqN9o8) * Create a new simulation and select both modules (make sure that the PK-Sim module is on top!). ![Image](/files/JN6IXkIHrTnIHFn1dWBD) In the next step, optionally select an Individual and Expression Profile(s). ![Image](/files/hKTrqInByjgPRPcZ94Pm) * The "Tumor" organ will now appear in the simulation. ![Image](/files/fPM20B3F7MxxnOel8VqA) * Tumor drug concentrations, etc. can now be plotted in the simulation. ![Image](/files/QZ5nwCtoEwE4K2F9ZU9Z) ![Image](/files/bERAz19XZkqhfXQMtePJ) ## Setting up a Reaction Network This chapter will give a brief overview of: * how a simple reaction network is established within the building blocks * how different building blocks are combined to get a functioning network (simulation) * how a dynamic simulation of the newly established reaction network can be performed This workflow will be described in detail below. ### Step 1: Create a new project: * Start MoBi® * Click on the **File** tab and select **New Project** or * Use the shortcut key **Ctrl+N** ### Step 2: Open the new Molecules building block named "Molecules": To open a building block, extend its tree view in the building block explorer and either: * Double-click on the appearing building block . * Right-click on the appearing building block and select **Edit** from the context menu. The building block is now opened in the main window and the ribbon view changed to the building block specific ribbon tab (Edit Molecules). ### Step 3: Create three new Molecules named "Educt", "Product" and "Drug": * Click **New** in the building block specific ribbon tab or right-click on the empty space in the building block (*Molecule List Tree View*) in the main window and select **Create Molecule**. * In the appearing window, select a name for the molecule and enter a **Constant** default start amount with the value set to 1 µmol. * Deselect the **Stationary** property (to indicate that the molecule is non- stationary) and click **OK**. In the main window, the molecules building block should now contain three list entries named "Educt", "Product" and "Drug". ### Step 4: Create a container where the reaction takes place: * Open the "Organism" building block in the spatial structure building block group. * In the new main window, double-click on the green container in the diagram area named "Organism". * Select the **Properties** tab in the lower half of the main window and using the right combobox of **Container Type**. Select: *Logical Container ...*. * In the diagram area, right-click anywhere and select **Refresh** in the context menu: the color of the green container named "Organism" should change to *blue*, which characterizes logical containers. * In the diagram area, right-click on the container named "Organism" and select Create Container in the context menu. * In the appearing "New Container" window, choose a new name for the container (here: liver), set the **Container Type** to *Logical Container ...*, and click **OK**. * Right-click on the new "Liver" container. Again, create a new container named "Plasma" with **Container Type** set to *Physical Container ...* and click **OK**. * Double-click on the new "Plasma" container. In the parameters tab below the diagram area click on the **Add Parameter** button. * In the appearing "New Parameter" window, specify a name for the parameter (here: Volume), verify that the **Dimension** is set to *Volume* and **Formula Type** to *Constant*, and set the Value to 1 liter. ### Step 5: Create a new reaction named "Re": * Open the reaction building block for editing. * To create a reaction, either click on **New** in the building block specific ribbon tab or right-click on the empty space in the diagram area of the building block edit window and select **Create Reaction**. * Add the molecules created in **Step 3** by either clicking on **Insert Molecule** in the building block specific ribbon tab or right-clicking on the diagram area of the building block edit window and select **Insert Molecule**. * A new window appears: select the molecules displayed in the list (select all three while holding down the **Ctrl** key) and click **OK**. To connect the molecule "Educt" as an educt of the reaction "Re", move the mouse to the edge of the molecule in the diagram area until the mouse cursor changes into a "Hand" symbol. . Click and drag your cursor towards the reaction until the appearing line snaps onto the *blue* circle (the educt port) at the lower left end of the reaction symbol. ![Reactions Building Block: Connecting Molecules to a Reaction](/files/-LOWQ3emVdxsJYQS3V0F) Repeat this procedure for the "Product" molecule and the *green* circle at the lower right corner of the reaction symbol, and the "Drug" Molecule and the *red* circle at the top of the reaction symbol. {% hint style="warning" %} The molecule "Drug" is now a modifier (as is indicated by the *red* circle) of the reaction that is neither consumed nor produced by the reaction, but required (as all participating molecules) to be present at the same location (even if at concentration zero) for the reaction to be generated in the simulation creation process as described later in **Step 9**. {% endhint %} ### Step 6: Specify the kinetics of the reaction: To edit the reaction "Re" and define its kinetics: * Double-click on the reaction symbol in the diagram area; * or right-click on the reaction symbol in the diagram area and select **Edit** from the context menu. Select the properties tab in the window below the diagram area. {% hint style="info" %} By default, all molecules are defined in the **Dimension** Amount. As reaction kinetics are computed from concentration values of reactants, volumes of the containers where reactions take place have to be taken into account. {% endhint %} We will now define the reaction kinetics as a reversible reaction in which the molecule "Educt" is: * consumed according to the *Michaelis-Menten* rate law: *k1\*Drug/V\*((Educt/V)/ (Km+Educt/V))* * produced according to the mass action kinetics rate law: *k2\*Product/V* By default, the **Formula Type** of the kinetics is set to **Formula** (an explicit formula). You can change this selection by use of the combobox, if needed. Now select the formula string input box to the right of the yellow warning sign with the exclamation mark and enter the chosen reaction rate: * k1\*Drug/V\*((Educt/V)/(Km+Educt/V))-k2\*Product/V The properties tab should now look like depicted below: ![Reaction Properties: Defining the Kinetics of a Reaction](/files/-LNl8PmwVNF95lPHFG3W) {% hint style="info" %} The color of the circles of the reaction symbol determines the sign of the kinetic formula. For molecules attached to the *blue* circle (always the *educts*) it is negative as they are consumed. For molecules attached to the *green* circle (always the *products*) it is positive as they are produced. {% endhint %} In the properties tab, two essential inputs are still missing: * An explicit formula requires a name as indicated by the symbol . * The specified formula cannot be parsed due to the unknown entities: *k1*, *k2*, *Km* and *V* as indicated by the symbol . First, a new formula has to be created. To create a new formula, click on the **Add Formula** button. A new window appears, where you can define a new name for the formula. Type in "r1" and confirm the name by clicking **OK**. The formula is also listed in the formula list in the formula tab located above the diagram area. The yellow warning sign indicates that the construction of our kinetic rate equation is not yet complete. To get a consistent formula, you need to assign the missing parameters to the reaction and add them to the referenced objects list. {% hint style="info" %} As depicted above, molecules are automatically added to the referenced objects list of an *explicit Formula* when connected to the reaction. The referenced objects are by default listed by the following properties: {% endhint %} *The table below belongs to note above.* | | | | --------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Alias | Defines the name by which the referenced objects are used in the Formula. If the name in the formula does not correspond to the Alias of the respective reference, a warning sign appears. | | Path | Path where the referenced object is located within the project. | | Dimension | Dimension (e.g., *Volume* l or *Concentration* µmol/l) of the referenced object. | {% hint style="warning" %} Formulas are automatically stored *even if incomplete*! However, they can be completed any time later. A list of all formulas used in one building block can be found in the formulas tab next to the main tab of each building block in edit view. {% endhint %} ### Step 7: Add new parameters: Select the parameters tab next to the properties tab. To create a new parameter: * Click on the **Add Parameter** button. In the new window * Select a new name: *k1*, for the first rate constant. * Select **Parameter Type**: *Local*. * Using the combobox, set the **Dimension** to *InversedTime*. * Select the **Formula Type**: *Constant*. * Set a **Value**: 1 *1/min*. Repeat the process for parameter *k2*. For parameter *Km*, select **Dimension** Concentration and the Constant **Value** 1 µmol/l. To add parameters to the reaction, go back to the properties tab. Go to the tree list "Possible Referenced Objects" on the right side of the window. The selected reaction "Re" should appear at the top of the tree. Extend the tree view of "Re". The parameters *k1*, *k2* and *Km* should be listed below "Re". To add the parameters to the list of referenced objects, drag & drop each parameter into the list to the left, where "Educt", "Product" and "Drug" are already listed. To add the volume parameter "V" to the list, select the bullet Relative Path. A new window appears where you can select the local reference point. Extend the tree and navigate to *Organism|Liver*. Select "Plasma" and click **OK**. Now, navigate to the same point (*Organism|Liver|Plasma*) in the tree in the "Possible Referenced Objects" window and drag & drop "Volume" into the referenced objects list. Change the **Alias** of "Volume" to "V". Your properties tab should now look like depicted below. ![Reaction Properties: Defining the Kinetics of a Reaction](/files/-LNl8PnGTOlAT4wHOw__) ### Step 8: Define start values: Before we can create a simulation, we need to define start values. To create new molecule and parameter start values: * Right-click on the molecule start values building block group in the building block explorer and select **Create Molecule Start Value Building Block** from the context menu. * In the appearing "Create new Start Values" window, define a name (here: "MSV") for the molecule start values building block and confirm by clicking **OK** . * Repeat the procedure for a new parameter start values building block using the name "PSV". ### Step 9: Create a Simulation from the newly defined building blocks: Before we can simulate, the reactions network of a simulation has to be created from the building blocks. To create a simulation: * Click on **Create** in the *Simulation* Group the *Modeling & Simulation* ribbon tab. * In the appearing "Simulation Creation Wizard" window, specify a name for the simulation. Here: "RN". * Confirm the simulation creation process by clicking **Finish** . A new simulation "RN" is added to the simulations explorer and automatically opened in edit mode in the main window. Your MoBi® program user interface should now look like depicted in below. ![Create a Simulation](/files/-LNl8Pn_kKGGn05X4rrs) ### Step 10: Simulate the dynamics of the newly created simulation of "RN": To run the simulation we first need to adjust the simulation settings: * Select the Settings tab of the simulation in the main window. * In the top half of the Settings tab set the **EndTime** to 0.25 h and the **Resolution** to 600.00 pts/h. Now we can run the simulation. To run the simulation, click **Run** in the simulation group of the modeling & simulation ribbon. To view the simulation results: * Select the **Results** tab of the simulation in the main window. * To the right of the window, click on or hover with your mouse over the autohidden chart editor view to slide out the chart editor. {% hint style="info" %} You can permanently dock the chart editor by clicking on the "pin" icon ![Image](/files/-LNl8PiV8fj-YvNWI59a). Undock the chart editor by again clicking on the icon ![Image](/files/-LNl8PnfBnAMbSc04a_n). {% endhint %} To display the simulation results in a plot window: * Extend the tree "Organ: Liver" in the *Data Browser* at the top of the chart editor, if it is not already open. * Select both checkboxes ![Image](/files/-LNl8Pnhk1uhOUtibRI1) in the column **Used**. You can now see the simulation results in the plot, and your **Results** tab should now look as depicted below. ![Simulation Results](/files/-LNl8Pnjpxp0KPiIbFIZ) # Features of Tables In this chapter you find the documentation of the table view, which is generally used throughout the Open Systems Pharmacology Suite. ## Overview In PK-Sim® and MoBi®, tables are often used for input and output, for instance in parameter lists, history, and the chart editor. The tables have several useful features whose availability in some cases depends on the context. In this section we describe the most important features on the example of the table **Physiology > Organ composition** in the tab **Anatomy & Physiology** of an individual in PK-Sim®. ![Organ Table](/files/-LNl8Qx_3iMIzPGxbDWU) Before we describe the features in more detail in the following subsections, we give a brief overview of the most used concepts and actions: * Column width - you can change the width of a column by dragging the separator line between two column headers ![Image](/files/-LNl8Qxwy33l82sbmiux). * Column order - you can change the order of columns by dragging a column header to another location in the Column Header Row. * Sorting - you can sort the rows by the content of a column by just clicking on the column header. The sorting column is marked by a triangle on the right of its header. * Filtering - you can filter the rows by a certain value of a column by hovering with the mouse over the right hand side of the column header and clicking on the filter symbol , which then appears. * Grouping - you can group the rows by dragging a column header to the grouping panel and vice versa. Right-click on a column header to get a **context menu** with more features. In the following, we simply use **Context Menu** to denote the context menu of a column header. The screenshot below shows a table * grouped by the Organs/Compartment column, * sorted by the Organ/Segment column, * filtered by Name = 'Fraction vascular', * and the name column moved left to the value column. ![Organ Table With Changes Applied](/files/-LNl8QxpI_SvjF-sPfMw) ## Sorting * To sort the rows of a table ascendingly by a column, click the column header. * Click on the column header again to toggle the sort order between ascending and descending row values. * Select **Clear Sorting** from **Context Menu** to undo the sorting. * To sort by multiple columns, you need to press the shift key when clicking on the column headers for sorting. The ordering within a multiple column sort depends on the sequence with which the columns have been selected for sorting. To alter this sequence you deselect a column by **Clear Sorting** from **Context Menu** and then re-select it. ## Grouping * To group the rows of a table by a column, drag the column header from the **Column Header Row** to the **Grouping Panel**, if visible, or select **Group by this column** from its **Context Menu**. * To show the **Grouping Panel**, select **Show Group By Box** from **Context Menu**. * You can group by several columns hierarchically. In order to do so drag a column header to the left or to the right of another column header in the **Grouping Panel**. * To ungroup the rows, drag the corresponding column header from the **Grouping Panel** back into the **Column Header Row** or select **Ungroup** from the **Context Menu** in the **Grouping Panel**. {% hint style="info" %} Note that the grouping feature is not available for all tables. {% endhint %} ## Filtering To filter the rows of a table do one of the following: * Hover with the mouse over the right hand side of the column header and click the appearing filter symbol ![Image](/files/-LNl8QxsgRYl9udHfFX8). Then select one or more values in the values list. The filter condition is displayed at the bottom of the table, where you can delete or edit it. * Select **Show Auto Filter Row** from **Context Menu**. An auto filter row appears as first row in the table. There you can enter values; use \* as wildcard. * Select **Filter Editor** from **Context Menu**. An filter editor dialog appears, where you can combine conditions for different columns. * Select **Show Find Panel** from **Context Menu**. The find panel with a single search field appears above the **Grouping Panel**. Here you can enter some text and all rows of which any field contains that text are displayed. You can easily combine different filter features, as exemplary shown in below. ![Organ Table With All Features Applied](/files/-LNl8QxumG9r7ZKkq5u-) ## Select columns * Select **Column Chooser** from **Context Menu**. * Drag a column header from **Column Chooser** to **Column Header Row** to show the column. * Drag a column header from **Column Header Row** to **Column Chooser** or outside the table to hide the column. {% hint style="info" %} The column chooser is not available for organ composition table. {% endhint %} ## Arrange columns * You can change the order of columns by dragging a column header to another location in the **Column Header Row**. * You can change the width of a column by dragging the separator line between two column headers ![Image](/files/-LNl8Qxwy33l82sbmiux). * You can adjust the width of a single column to fit its contents by double clicking its column header. * To automatically set an appropriate column width for all columns, select **Best Fit (all columns)** from **Context Menu**. # Chart Component ## Chart Display and Chart Editor The chart component is used in PK-Sim® as well as in MoBi® . It consists of two views, the chart display and the chart editor. The chart display displays a chart, the chart editor is used to create and edit charts. By default, the chart editor is auto hidden; when you hover over the vertical chart editor button on the right, the chart editor opens and you can edit the chart settings. To dock the chart editor click the auto hide button ![Image](/files/-LNl8PiV8fj-YvNWI59a). The button icon then changes to ![Image](/files/-LNl8PnfBnAMbSc04a_n), and the chart editor is docked. Afterwards, you are able to move the chart editor to other edges as well. To auto hide the chart editor, click the auto hide button ![Image](/files/-LNl8PnfBnAMbSc04a_n) again. The chart editor consists of several subviews that depend on the number of tabs specified in the chart layout and that comprise: * the data browser table for browsing and selecting data to be displayed in a chart, * the curves table and the axis table in the tab **Curves and Axis Options** for editing curve and axis properties, * the tab **Chart Options** for editing chart properties like title, legend position or back color. * the tab **Chart Export Options** for editing chart and font sizes used when exporting a chart. {% hint style="info" %} The most frequently edited chart elements, axes and curves, can be edited directly from the chart display without using the chart editor. Just double click the axis or curve you want to edit or right click and select **Edit** from context menu. {% endhint %} ![Data Chart](/files/-LNl8RsKzymmEvqVMnSl) ## General Chart Basics For a better understanding of the workflows and features of the chart component, we briefly introduce some chart basics. Charts are used to visualize data. In the Open Systems Pharmacology Suite, data consists of time series from simulation and measurements. Charts consist of axes and curves. Typically, the x-axis has the dimension time and the y-axis to dimension concentration. Curves are based on time series, mostly one curve corresponds to a single time series, in this case the x-values represent the time axis and the y-values are the corresponding functional values of the time series. However, curves can also correspond to two time series with the same time scale, in this case the x-values are the values of the first time series and the y-values are the values of the second time series. Thus, for example, concentrations can be plotted against other concentrations. Creating a chart consists of selecting the data and editing the curve / axis / chart settings. The chart settings and chart export settings can be reused to create uniform charts for a sequence of simulation projects. In the next sections, we describe the basic workflow and the subviews in detail. ## Creating a Chart Creating a chart consists of two steps: 1. Select the data for the curves in the data browser. 2. Edit the chart settings * Edit curve options, * Edit axis options, * Edit chart options. We describe these steps in the following subsections. ## Selecting Data The data browser contains one row for each available time series. Depending on the complexity of your model, there can be thousands of rows. (For convenience, trivial time series with the constant value 0 are automatically excluded.) Properties of the time series are displayed in the columns of the data browser, e.g., Organ/Container, Compartment, Molecule, Name, Dimension, Used. To organize these data there are three concepts, which we describe here only briefly. * Grouping - you can group by a column by dragging it from the column headers to the so called grouping area and vice versa. * Sorting - you can sort by a column by just clicking on the column header. * Filtering - you can filter a column by moving the mouse to the right side of the column header and clicking on the filter symbol, which appears. Right-click on the column header to get a context menu with more options. In the figure below, data are grouped hierarchically by organ and compartment, they are sorted by molecule and filtered by the condition **Dimension = 'Concentration'**. ![Data Browser](/files/-LNl8RsMrVXZE-zEYr2k) To select data: 1. organize your data according to your needs, 2. do one of the following: * Check the checkbox ![Image](/files/-LNl8QfSrkOT_RUDh53f) of a row in the used column, * Drag a row from the data browser to the curves table, * Select multiple rows by holding the CTRL or the SHIFT key when clicking them and drag them together to the curves table or check the checkbox **Use selected** in the right upper corner of the Chart Editor. 3. Repeat step 2 until your data selection is complete. {% hint style="info" %} The creation of charts with alternative x-values, e.g., other concentrations, is explained in “Using Alternative X-Values”. {% endhint %} After selection, the corresponding curves are automatically shown and listed in the curves table. To deselect data, do one of the following: * Uncheck the checkbox ![Image](/files/-LNl8Pnhk1uhOUtibRI1) of the row in the used column of the data browser, * Click the **Delete** button ![Image](/files/-LNl8RsPTW2x1Ae9es_5) on the right side of the curve row in the curves table. * Click the row header on the left side of the row to select the curve row and press **Delete**. {% hint style="info" %} When a Parameter Identification or Simulation chart is open, the data are first grouped by their category and the checkbox **Link Data to Simulations** is displayed. Selecting this check box links the observed data to the simulation outputs they are mapped to. When the checkbox is selected, (un)selecting a simulation output will result in the (un)selecting corresponding observed data. {% endhint %} ![The view for PI and Simulation Charts](/files/HzZSB58bVWCKg2cw0pTm) ## Editing Curve Options The properties of the curves can be edited in the curves table. Each curve is displayed in one row, and the properties of the curves are displayed in different columns. The most important columns are: | | | | ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | y-Axis |

The first curve is assigned to the first y-axis Y and the dimension of the axis Y is set from the corresponding time series. The next curves are assigned to the same y-axis as long as their time series have a compatible dimension.
For the first curve based on a time series with a different dimension, a second y-axis Y2 is created with that dimension and the curve is assigned to that y-axis.
If there are curves based on time series with further dimensions, they cannot be displayed, because they do not match one of the two possible y-axis dimensions. Then this row is marked with an error symbol and you have to adjust the axes dimensions and the y-axis property of the curve manually.

| | Curve Name |

The curve name is created automatically when inserting a new curve. For simulation data it consists by default of organ, compartment, molecule and name of the time series. You can overwrite this name manually.
You can select additional discriminating curve properties for curve name generation at chart options of user settings: simulation name, top container/organism name, dimension name.

| | Color | Colors are automatically selected for the first 16 curves; however, you can adjust them by clicking on the color editor in the cell. See also paragraph below for coloring curves with the same color. | | Style | You can select between the following styles: Solid, Dash, Dot, DashDot and None (for measured data points). | | Symbol | You can select from the following symbols: None (default for simulation data), Circle, Diamond, Triangle, and Square. | | Thickness | You can select line thicknesses as 1, 2, and 3. (Hidden by default) | | Visible | To hide a curve from the chart, uncheck this checkbox. | | In Legend | To hide an entry in the legend for a curve, uncheck this checkbox. For different observed data curves, you can use for example only one legend entry. | If a row header or cell content cannot be fully displayed, the full content is shown in a tooltip when you hover with the mouse over that field, as shown below: ![Curve Options](/files/-LNl8RsRU4b4if4pnbZj) ## Editing options of multiple curves In the “Curves and Axis Settings” Tab of the Chart Editor a new context menu item has been added called “Edit options for selected”. It is only visible when the user has selected at least two rows in the curves table. ![Edit Multiple Curves Context Menu](/files/97FA8rAwIs3qE7hdxCRD) Selecting this option opens a new dialog listing the common options of the curves. Initially the values for the options are not set, and if the user leaves one of the options in this initial state, that option will not be edited – meaning that the selected curves will retain for that option the value they had before opening the dialog. ![Edit Options Dialog](/files/3E7mBa96xbnUQ1YcHMv1) ### Coloring curves with the same color Often you may want to use the same color for different curves, e.g. for curves of the same molecule or organ or for observed data. You can easily copy the color from one curve to another by just dragging the color symbol from one curve to the color field of another curve. During the dragging process, a **+** symbol is shown. If you want to color different curves - for instance of observed data - with the same color, you can also use the **Default Color** of the y-Axis. 1. In the axes table, select the column **Default Color** in the column chooser (right click on column header). 2. Change the **Default Color** for the corresponding y-Axis to the intended color. 3. Select the curves from the data browser. 4. Reset the **Default Color** for the y-Axis to White which deactivates default color. ### Coloring grouping tab A tab called "Curves Color Grouping" is displayed in the charts with observed data sets. In the tab the user can select one or more metadata, according to which the observed data sets will be grouped and given the same color. Clicking the “Apply Color Grouping” button changes the color of the observed data sets in the chart according to the selection, and then the selection is cleared. The user can then choose a new selection of metadata and change the coloring once again. ![Color Grouping Tab](/files/vieSeRDXQhaqHr1Dsik8) #### Observed Data color grouping when adding to charts When adding observed data sets to a chart via drag-and-drop of a folder (or multiple folders), all data sets within one folder can be assigned to a single color. This behavior is optional and can be changed by (un)selecting the checkbox "Color by folder when adding to chart" in the context menu of the “Observed Data” entry of the building blocks explorer. This setting is a central configuration and applies for all subfolders. ![Color Grouping Option Context Menu](/files/28Nsp6qj302SITF4F9Ef) Alternatively, this feature can be toggled on and off from the User Settings, under “Utilities” -> “Options” -> “General” -> “Colors”: ![Color Grouping Option In Settings](/files/YjmiePjb6IH33LZKfgoO) When this option is selected and whole folders are dragged and dropped into a plot, the observed data from the same folders will be assigned the same color. However, when the user selects individual observed data sets instead of folders and drags and drops them on the plot, then each one will be assigned a new color, and they should not be grouped according to the folder they belong to. ### Creating clear legends To make you legends clear and readable - especially when exporting them - you can do the following * Edit the curve name. Curve names are automatically composed (in MoBi you can control the curve name composition via some settings in the Chart Options). Mostly, not all information contained by default is relevant in a certain situation and therefore the names should manually be reduced or renamed to contain the relevant information. (If, after renaming you, are in doubt about the data of your curve you can always identify it by selecting the column y-Data from the column chooser of the curves table.) * Hide needless legend entries in particular for multiple observed data sets. If you do not intend to refer to single individuals, uncheck the checkbox **In Legend** for all but one observed data set. * Reorder your legend entries to show the most important entries on top. You can reorder them directly in the legend by dragging the line symbol to another symbol which moves the legend entry of the dragged curve just above the entry where it is dropped. You can reorder them also by dragging the row headers (the small gray area on the left of a row) in the curves table. ## Editing Axis Options You can edit properties of axes in the axes table. There is always one unique x- axis and one y-axis. You can add up to 2 additional y-axes by clicking the button on the right end of the y-axis row. Each axis is displayed in one row, and the properties of the axes are displayed in different columns. You can select columns which are hidden by default using the **Column Chooser** and right click on the column header. The most important columns are: | | | | ------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Axis | Type of the axis. | | Dimension | The dimension of an axis is automatically determined by the selected data, see “Editing Curve Options” for details. You can change the dimension here manually in more complex situations. | | Caption | This field is empty by default. Then dimension and unit are displayed as axis caption in the chart. You can enter an alternative caption here, which is displayed instead of the dimension name. (Hidden by default) | | Unit | You can select a unit for the dimension of the axis from a list. | | Scaling | You can switch between Linear and Log scaling. In case of Log scaling, values less than or equal to 0 are not displayed. By default, the scaling for y axes is **Log**, but in MoBi® you can change this in the Chart Options. | | Numbers | You can select the numbers representation from Normal, Scientific and Relative. If you select Relative for a y- axis, each curve is displayed relative to its own maximum value, which then corresponds to 100% . (Hidden by default) | | Min, Max | Empty for automatic range to show all values. You can override the values to restrict the displayed range. To return to automatic range, delete Min or Max value. | | Default | Curves added to a y-axis get this linestyle by default. This way, Linestyle in the chart, curves can be easily correlated with their y-axes. You can change the default linestyles here, which are by default solid for y, dashed for y2 and dotted for y3. | | Default Color | If a color different from White is selected, curves added to a y-axis get this color by default. (Hidden by default) | | Grid | You can check this to display grid lines at the major ticks of the axis. | {% hint style="info" %} The Min and Max values are overridden by zooming the chart. {% endhint %} ## Editing Chart Options You can edit the properties of the chart in the chart options tab. | | | | -------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- | | Name | Name of the chart, which is used as tab header. | | Title | Title is displayed above the chart. | | Description | A description is displayed below the chart. To insert line breaks press the **Enter** key. | | Legend Position | You can select whether the legend is displayed at the right or at the bottom of the chart, inside or outside of the diagram area. | | Chart Color | The color of the chart. | | Diagram Background | The color of the diagram background. You can change these colors in the Chart Options. | | Side Margins Enabled | You can check to leave about 5% margins at each side of the chart or uncheck to fit the diagram area exactly to the Min and Max values of the curves. | ## Editing Chart Export Options You can export charts to the Working Journal or other applications by copy & paste. To copy the chart, just right click into the chart area and select Copy to clipboard. You can define the size of the exported chart in the **Chart Export Options**. Then, the exported chart is independent of the current size of the application window. You can also define the font sizes of the exported chart to get readable legend entries in your slides for example. In the **Chart Export Options** tab, you can select **Preview these settings in Chart Display** to preview any changes you have made in the settings of the **Chart Export Options**. You can select **Include origin data** and show the title of the PK-Sim® or MoBi® file, the name of simulation and the date of creation beneath the Chart®, as illustrated in the image below. This can be useful for example, if you want to refer to the simulation state used in a chart in a presentation. ![Chart Export Options](/files/-LNl8RsW5cVOCmLgvaeM) You can edit the following properties of the exported chart in the tab **Chart Export Options**. | | | | --------------------- | --------------------------------------------------------------------------------------------------------------- | | Width \[px] | The width of the chart in pixel units. | | Height \[px] | The height of the chart in pixel units. | | Font | Here you can select the text font. The standard font is Microsoft Sans Serif. | | Font size axis | You can adjust the font size of the axis via a drop down menu. | | Font size legend | You can adjust the font size of the legend via a drop down menu. | | Font size title | You can adjust the font size of the chart title in case you have defined one in **Chart Options**. | | Font size description | You can adjust the font size of the description of the chart in case you have defined one in **Chart Options**. | | Font size origin | You can adjust the font size of the origin data in case you have selected the **Include origin data** option. | ## Zooming the Chart To zoom into the chart, do one of the following: * Hover the mouse over the chart. A zoom symbol appears. Press the left mouse button and drag the mouse to select a rectangle. Release the mouse button to zoom into the selected rectangle. ![Image](/files/-LOWQ20o53MShWED0Mnm) * Explicitly define the range to be displayed in the Min and Max columns in the Axis Options. * Use the mouse wheel while the mouse pointer is located in the chart area. To reset the zoom right click on the chart area and select **Reset Zoom (Ctrl+0)** or use the shortcut **Ctrl+0** (Do not use the 0-key from the numeric block, but from the typewriter keys.). ## Further Actions ### Saving and managing chart settings You can save the chart settings (Chart Options and Chart Export Options, Curve and Axes Options) in different Chart Templates and reuse them in a simulation. This is useful for example, if you want to switch between different settings. You can also save and load these Chart Templates to files and reuse them in other simulations. Moreover: * in PK-Sim®, the Chart Templates are reusable in any clone of a simulation, * in MoBi®, the Chart Templates and Curves Selection are part of the Building Block Simulation Settings and can be reused like any other Building Blocks. The chart manager can be accessed directly from the chart editor after running a simulation. The following options are available: * Apply Template: choose from a list of saved templates, * Create New: create a new template based on current settings for data, curves, axis and chart options, * Update Existing: changes the settings for the template to the current settings for data, curves, axis and chart options, * Manage Templates: brings you directly to the chart template manager that displays an overview of all settings in a template which can all be edited. ![Accessing chart templates and chart manager from the chart editor](/files/-LOWQ20qL1Nv3_F0vcXw) In the chart manager, templates can be managed in the left hand side window and settings for an individual template can be edited in the two right hand side windows. ![Management and editing of chart templates in the chart manager](/files/-LOWQ20sd4ZI0HT1xbZA) The following options are available for managing templates: * Clone: useful when changing specific settings based on an existing template. * Save template to file: allows you to reuse this template in another simulation settings building block, simulation or project. * Delete template In addition, a template can be loaded as .xml file using the button. In the right panel, the user can specify which curve will be selected as output and how it will be displayed. An automated algorithm is implemented that decides which curves are selected when a certain template is chosen. Decision criteria are based on the output path (Y-Path) and the output type (Y-Type). The following decision scenarios are feasible: * If a selected output matches both, Y-Path and Y-Type, it will be selected and the curve name will be used as is. * A selected output matches the Y-type, but not the Y-Path of a template. The Y- Path of the output is for example **Organism|Venous|Blood|Plasma|Diclofenac**. The algorithm will then try to find all output located in the container **Organism| Venous|Blood|Plasma**. If only one output is found, the curve name will be used as is. If two or more outputs are found, the curve name will be ignored and a new unique name will be generated based on the actual path of the output. Sometimes, this heuristic approach might result in many selected curves at once. If more than ten curves will be selected, the user will be asked whether be wants to proceed or choose a different template for display of the selected output curves. {% hint style="info" %} All changes to a template or selection of output are made at the level of an individual simulation. The simulation settings for the project remain unchanged, until the user explicitly updates the changes to the project simulation settings building block using the context menu as shown below. {% endhint %} ![Changes in the simulation setting can be committed to the settings at the project level](/files/-LOWQ20vHChw6UgJ_sDY) ### Selecting Editor Layouts You can select one of the following predefined editor layouts: | | | | -------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Standard View | The chart editor is auto hidden. The data browser is displayed in the upper area of the editor, the curves and axis options are displayed in the lower area. The chart options are displayed on a different tab since they are used less often. | | Tabbed View | The chart editor is auto hidden. Data browser, curves options, axis options, chart options are displayed on four different tabs. Use this view, when you need maximal space for data browser or curve options display. | | Two Tabs View | The chart editor is auto hidden. The data browser and curves options are displayed on the first tab, axis options and chart options are displayed on the second tab. Use this view, if the automatic axis settings fulfill your needs. | | Variable X-Axis View | This layout is similar to standard view, but display all columns necessary for selection of an alternative x-axis (see [Using Alternative X-Values](#using-alternative-x-values)). The chart editor is docked. Use this view, if you want to use an alternative x-Axis. (Available in MoBi® only.) | {% hint style="info" %} Save your preferred Editor Layout to your user settings. Just select Save to User Settings from the Layout menu at the top of the Chart Editor. In this layout are stored the selected view and column settings in the subviews like visibility, order, column width and grouping. {% endhint %} ### Using Alternative X-Values As mentioned in the introduction of this section, typically one curve corresponds to a single time series in which the x-values represent the time axis and the y- values are the corresponding functional values, such as concentration. ![Concentration versus Time Plot](/files/-LOWQ20yxFvAlNlcpxBM) However, curves can also correspond to two time series with the same time scale. In this case, the x-values are the values of the first time series and the y-values are the values of the second time series. Thus, concentrations can be plotted against another concentration or a fraction of the dose, for example. To select other x-values than the default ones, do the following (you can skip steps 1 and 2 when using the editor layout Variable x-Axis View): 1. Show the x-Data column in the curves table. In detail: 1. Right-click on the columns header row of the curves table. 2. Select **Column Chooser**. 3. Drag the x-Data (and y-Data, if you like) to a position between two other column headers in the header row. 4. Close the **Column Chooser**. 2. Show the dimension column in the axis table (like in step 1) and in the data browser. 3. Drag the time series with same the time scale and the intended values from the data browser to the x-Data field of the desired curve in the curves table. An error symbol appears at the x-Data field, because now the x-Data and the x-axis have different dimensions, which cannot be resolved automatically. ![Image](/files/-LOWQ21-j9rk2bSOYKG4) 4. Change the Dimension of the x-axis in the Axis Table to the dimension of the x-values manually. 5. Change curve or x-axis caption according to your needs. Now the concentration is plotted against the selected x-values. ![Concentration versus Concentration Plot](/files/-LOWQ2139NVqPc6Ion5V) ### Chart Options in User Settings In MoBi®, you can change the default editor layout and the default curve name generation in the **Chart Options** tab within the **User Settings** dialog (click **Options** in the Utilities ribbon tab). All options here are stored in the user settings and apply for newly opened charts and curves. # Comparison of Building Blocks The comparison of building blocks can help when to compare different versions of a model for e.g. reporting purposes. Alterations of individual building blocks can be seen at a glance. Converting models can also lead to alterations in building blocks. This can be the case, if one version of a model uses a functionality of PK- Sim® that was not available in the older version, e.g. tagging building blocks. A further, rather special case, is a listing of extended start values upon comparison. If, in MoBi® parameter or molecule start values are incomplete, they are extended during the **Create Simulation** process. These amended start values will be listed if the respective building block before and after creation of a simulation are compared. Generally, only two building blocks can be compared at a time. Comparison of building blocks can be done within a group. For example, to compare two different molecule building blocks, press the Control key and mark both building block by left click. Upon right click, the context menu appears as shown below. ![Comparison of different molecule building blocks within a group](/files/-LOWQ2w00-n_wd2UJBJ4) Comparison of building blocks can also be done within a simulation when a building has been altered and the differences to the original version need to be known. This is illustrated in the example shown below in which using the **Show differences** option in the context menue will produce a list of changes. Chosing the **Update from building block** option will reset all settings in the building block to those of the original. ![Comparison of different molecule building blocks within a group](/files/-LOWQ2w3XtMr3EjeORZR) Comparison of building blocks can also be done between two simulations on the same kind of building block as shown below. ![Comparison of molecule building blocks between two simulations](/files/-LOWQ2w6n8ni5xZFVXsd) Comparison of building blocks yields a list as shown below that can be filtered for better overview. To do so, right click on the small filter symbol in the top right hand corner of the row header and choose the filter setting from the context menue. ![Filter your comparison list for better ovierview](/files/-LOWQ2w8aFB_FOsfgPHL) Comparison can be made according to specific settings defined by the user. The value entered for **Comparison tolerance (relative)** is a multiplication factor that sets the limit for two values being equal. For example, if this is set to 0, then two values need to be exactly the same for being considered equal. In contrast, setting the relative tolerance to 1, the values are considered equal. By default, the relative comparison tolerance is set to 1E-5. Using this setting, two values are equal if - in a first approximation - the first five digits after the decimal point are equal. The tolerance has no effect when comparing non-numerical values, like "present/ absent". A derived parameter can be defined by a formula that uses other parameters. Choosing the option **By values**, numerical values in the formula or the output of the formula are compared. Here, no limit for being equal can be introduced and numerical values need to be identical for being considered equal. All numerical values that differ between the two building blocks are compared. Choosing the option **By formula** compares the structure of the formulas. Both comparison criteria can be limited to impacts on the results of the simulations that contains the compared building blocks. ![Define your comparison criteria using these settings](/files/-LOWQ2wDYlt2F4bHoqMo) # Parameter Identification The first three chapters provide a basic understanding of the Parameter Identification tool: background and basic workflow and illustration in a simple example. In the following chapters you find more detailed descriptions of the features and configuration of the tool and a more complex second example of a parameter identification. ## Background The models built by PK-Sim® or MoBi® depend on a lot of input parameters which are based on literature values, measurements, databases, assumptions. For a given set of input parameters a number of output curves is computed in a **simulation**. Often, experimental data for the outputs are given and the reverse question is asked: Which input parameters lead to a simulation with output curves corresponding to the given experimental data? This reverse problem is called **Parameter Identification**: which values of certain input parameters yield simulation outputs that fit the observed data? A **Parameter Identification** problem is a kind of optimization problem: Minimize the residuals between observed data and corresponding simulation output by varying selected input parameters in a given range. (For a definition of residuals see the table “Scaling”) A variety of algorithms exist to solve optimization problems. The required effort and the quality of the solution depend on several factors, e.g. number and bounds of the input parameters of interest, complexity of the model, quality of start values for the input parameters. Because not all possible combinations of input parameter values can be evaluated, sometimes not the global optimum is found, but a so called local optimum. The user should be aware that a **Parameter Identification** as an optimization problem can become challenging, in particular for complex situations with many input parameters of interest or missing knowledge about their range. In a lot of situations the available **Parameter Identification** features of the Open Systems Pharmacology Suite allow you to identify unknown parameter values much easier than by manual trial and error. ## Overview of the workflow Within a Parameter Identification you have to perform the following steps: ### Prepare simulations In order to use the Parameter Identification tool, you should add all observed data you want to use to one or more simulations. Ensure that meta data for **Organ**, **Compartment**, **Molecule** is up to date, because this meta data is used for automatic mapping to outputs. In the simulations which will be used for Parameter Identification, select all outputs to be mapped to observed data. {% hint style="info" %} Selecting the input parameters of interest as **Favorites** makes it much easier to select those parameters later in Parameter Identification. {% endhint %} ### Create a Parameter Identification A Parameter Identification can be based on one simulation or several simulations which correspond to different experiments. To create a Parameter Identification, multiselect those simulations and select **Start Parameter Identification ...** from the context menu. ### Map outputs to observed data A mapping of observed data to corresponding simulation outputs is done automatically according to Organ, Compartment and Molecule meta data. Additionally, you can edit the mapping manually. ### Define Identification Parameters You have to select those input parameters which should be varied and identified. Each of these Identification parameters can be linked to corresponding input parameters in different simulations. ## Configure Optimization You can select between three optimization algorithms, edit their standard settings or change the usage of **Lower Limit Of Quantification** (LLOQ) values. ### Run Optimization After finishing the previous steps, you can run a Parameter Identification through the Ribbon Bar “Run & Analyze”. Running the Parameter Identification does not block the application, so you can proceed with manual work in your project. However the changes made in referenced simulations are not reflected in the *running* Parameter Identification. Multiple Parameter Identifications can be run in parallel. The “Run & Analyze” Ribbon Bar reflects the state of the currently selected Parameter Identification. ### View results After the Parameter Identification is finished, you will find the parameter values and corresponding output curves. Other views can help to assess the quality of the result, e.g. Predicted vs. Observed values for drug concentration or the correlation between Identification Parameters at the identified parameter values. During the Parameter Identification Run you can get visual feedback about the current state. If you like, you can stop the Parameter Identification manually. ## Simple Example For a hands on exercise, open the example project Theophylline.pksim5. You can download the project from . 1. In the Simulation Explorer mark the two simulations "*Kaumeier IV 208 mg fit*" and "*Kaumeier oral solution 185mg*" and select **Start Parameter Identification ...** from the context menu. 2. A new view for *Parameter Identification 1* is displayed and the tab **Data** is opened. On the left, the simulations with the assigned observed data are displayed. On the right, a list of mappings from outputs to observed data is displayed. For each observed data set for concentrations and fractions the corresponding output is mapped automatically (based on the Organ, Compartment, Molecule meta data). ![Parameter Identification - Mapping of outputs and observed data](/files/-LNl8bKIJecCBqXQ2AWH) 1. Switch to the next tab **Parameters**. Here, you have to define the parameters for identification. On the left, a list of all parameters grouped by **Simulation** and **Organ** is displayed. You can reorder the list for a more convenient view: 1. In the column **Favorite**, filter for checked to display just the Favorites. 2. Ungroup the columns **Simulation** and **Organ** (by right click on the column names you find that entry in the context menu). 3. Group by column name. Select both Lipophilicity parameters and click the upper **Add** button, then select both GFR fraction parameters and click the upper **Add** button again. Now, you have selected two identification parameters each linked to both corresponding simulation parameters. Switch to the next tab **Parameters**. Here, you have to define the parameters for identification. On the left, a list of all parameters grouped by **Organ** and **Name** is displayed. (If you are interested only in the Favorite parameters you can filter the column **Favorite**.) By default, all **Favorite parameters** are already selected as **Identification Parameters** in the right list of Identification Parameters. In this example project *Lipophilicity* and *Specific Clearance* were selected as Favorites. Here we want to identify the *GFR Fraction* instead of *Specific Clearance*. Remove *Specific Clearance* from the list of Identification Parameters and keep the *Lipophilicity* parameter. Then select both *GFR fraction* parameters (Expand Kidney/GFR fraction) and click the upper **Add** button. Now you have selected one new identification parameter linked to both corresponding simulation parameters. Enter Minimum Value 0 for both **Identification Parameters** and Maximum Value 2 Log Units for Lipophilicity and 1 for GFR fraction. Parameter Identification - Definition of Identification Parameters data 2. In the tab **Configuration** keep the default settings. 3. In the Ribbon Bar **Run & Analyze** click **Show Visual Feedback** and then Run to start the optimization. Parameter Identification Ribbon data 4. Now the **Visual Feedback Window** shows the intermediate state during the Parameter Identification Run. Parameter Identification - Visual Feedback data 5. After some iterations, the run is finished and you can switch to the tab **Results**. Parameter Identification - Results data You can transfer the optimized values for the parameters to the simulations by clicking **Transfer to Simulation**. Or you can select one of the **Analyses** views from the Parameter Identification ribbon. If you are not satisfied, you can change mapping of outputs or definition of Identification Parameters and run the Parameter Identification again. ## Creating a Parameter Identification To create a new Parameter Identification, do one of the following * Mark one ore more simulations for the Parameter Identification in the Simulation Explorer and select **Start Parameter Identification ...** from the context menu. * In the ribbon bar **Parameter Identification** click **Create** . * In the Simulation Explorer right click the Parameter Identification root node and select **Add Parameter Identification** from the context menu. The Parameter Identification view is displayed and the tab **Data** is opened. To add an additional simulation, drag & drop the corresponding node from the Simulation explorer to the Simulations list in the Parameter Identification view or use the button Add simulation. In the Simulation Explorer, the Parameter Identifications are also displayed in a tree. Using the context menu, you can * rename a Parameter Identification, * clone it in order to reuse the Identification Parameter Definition or the mapping of outputs to observed data, * add a Parameter Identification to a Journal page, * export the Parameter Identification definition to Matlab, * delete a Parameter Identification. ## Mapping Simulation Outputs to Observed Data A mapping of observed data to corresponding simulation outputs is done automatically according to **Organ**, **Compartment** and **Molecule** meta data of observed data and path elements of the outputs. One observed data item can be mapped to one output only, but the same output can be mapped to several observed data items. {% hint style="warning" %} Because meta data of observed data can be incomplete or wrong, you should check whether the right output is mapped to each observed data item. In case of different outputs with the same meta data (this can happen at least in MoBi), you should also check whether the automatically chosen output is correct. {% endhint %} You can also edit the mapping manually by selecting Output and Observed Data from the comboboxes. {% hint style="info" %} In case of incomplete or missing meta data, it is recommended to correct the meta data first to enable automatic mapping. {% endhint %} For each mapping, the scaling can be defined as Lin or Log which determines the residual calculation. **Scaling** | | | | --- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Lin | Residuals are calculated as: Simulation value - Observed value. This means that the residuals are defined by absolute differences. If the magnitudes of values are different for different parameters, the different magnitudes of residuals should be harmonized by corresponding weights (reciprocal values). Linear residuals are always calculated in the internal units. | | Log | Residuals are calculated as: log(Simulation value) - log(Observed value) = log (Simulation Value / Observed Value). This means that the ratio of values is considered which is independent of the magnitude of the value. But for very small observed values, in particular close to 0 values, this can lead to problems, because log(10E-N) = -N can becomes large. Then, the weights should be manually adjusted or LLOQ handling should be adjusted in the **Configuration**. (See “Configuration of Optimization”) | To reflect the quality or importance of the Observed Data item or to balance different magnitudes of values in case of Lin scaling, you can edit the weights of each mapping. If you select a mapping, the corresponding Observed Data is displayed as table and chart in the bottom area. There you can edit pointwise weights, e.g. to reduce or remove influence of outliers. {% hint style="info" %} In MoBi®, you can freely define observers to match any kind of observed data. In order to enable the automatic mapping ensure that the meta data for Organ, Compartment and Molecule is the same for corresponding observed data and observers. Therefore, you can define the observers for specific Containers and Molecules and/or edit the meta data of the observed data. {% endhint %} ### Handling of missing values for residuals For every observed data time point, the respective time value is added to the output interval of the simulation. This way, simulated value exists for each observed time point, and no interpolation of simulation results is required for the calculation of the total error. ## Defining Identification Parameters In the tab **Parameters** you can select the parameters which should be identified. If you have different simulations in one Parameter Identification, you have to decide, if one **Identification Parameter** is linked to *multiple* **Simulation Parameters** or *one* **Simulation Parameter** only. (If necessary you can even link different simulation parameters from the *same* simulation to *one* Identification Parameter.) If you have, for example, two simulations for two individuals with the same compound you may have one identification parameter lipophilicity which is linked to both lipophilicity parameters in the two simulations. At the same time, you define two identification parameters for the individual reference concentrations of a certain enzyme. In general, you should select **Identification Parameters** which are informed by the available observed data. You should be aware that the more Identification Parameters you define, the higher the complexity of the optimization problem. {% hint style="info" %} For the efficient selection of **Simulation Parameters** it is helpful to mark those input parameters as **Favorites** in a Simulation. For convenience by default all **Favorite parameters** are automatically selected as **Identification Parameters**. In the Parameters list of the Parameter Identification you can filter then by *checked* Favorites (here you cannot edit the Favorites). {% endhint %} If you like, you can ungroup the column Organ (via the context menu). So you get a list of Favorite Parameters with corresponding Simulation Parameters. * To define one Identification Parameter for all corresponding Simulation Parameters, simply select them all and click the upper Add button. * To define one Identification Parameter for each Simulation Parameter per Simulation, select them subsequently and click the upper Add button each time. * To add Simulation Parameters to an existing Identification Parameter (e.g. after adding another simulation to the Parameter Identification), select the Identification Parameter and the Simulation Parameter(s) and click the lower Add button. * To unlink a Simulation Parameter from an existing Identification Parameter, click the Unlink button ![Image](/files/-LNl8bKasDFu-8c17ZbX) in the Identification Parameters Simulation Parameters list (bottom right area); the Simulation Parameter is then unlinked from that Identification Parameter and a new Identification Parameter is generated for it. Of course, you can use other ways to filter, sort and group the list of Simulation Parameters. And you can use the Text Filter to filter by a text element in any column. Use enclosing quotation marks to search for composite strings, otherwise a search is conducted for both strings. ![Text Filter in List of Simulation Parameters](/files/-LNl8bKcg0_NK_ALwnQR) After selection of the Identification Parameters you should define their **Minimum and Maximum Values**. With these ranges you define the solution space of the optimization problem. Per default, the value of the first corresponding Simulation Parameter is used as a **Start Value**. You can edit this value manually or reset it to the Simulation Parameter value, e.g. after change of value in simulation (see column Value in the list of Simulation Parameters). By **Scaling** you define how the Identification Parameter is modified during optimization; if the magnitude of the parameter is not known, Log scale should be selected. Per default, the value of the first corresponding Simulation Parameter is used as a **Start Value**. You can edit this value manually or reset it to the Simulation Parameter value, e.g. after change of value in simulation (see column Value in the list of Simulation Parameters). By **Scaling** you define how the Identification Parameter is modified during optimization; if the magnitude of the parameter is not known, Log scale should be selected, which requires a **Minimum Value** > 0. In special cases you may want to couple two simulation parameters but not by the same value, e.g. you know that the specific clearance of metabolite is half of compound's specific clearance. In this case you can add both Simulation Parameters for specific clearance to one Identification Parameter, check **Use as Factor** and use e.g. a Minimum Value of 0.5 and Maximum Value of 2. Then both specific clearances are varied in parallel by multiplication of the respective simulation value with the same factor between 0.5 and 2. ## Configuration of Optimization You can configure the handling of LLOQ values, select among three optimization algorithms and edit the settings of the selected optimization algorithms. When checking **Calculate Sensitivity** at the end of the optimization, the partial derivatives are calculated locally for the optimized parameter values. From those, a **Covariance Matrix** and **Correlation Matrix** are calculated which give some information about *local sensitivity* of **Identification Parameters**. Additionally, you have special options to vary calculation methods (PK-Sim only) or to start multiple optimizations with randomized start values. ### Handling of LLOQ values You can decide if data values below LLOQ should be used or removed and how they should be handled in the residual calculation. **Remove data below LLOQ** | | | | --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Never (default) | All LLOQ values are used. In particular, for sparse data, the information that for a certain time point the value was measured and is between 0 and LLOQ can be relevant. | | Always | No LLOQ values are used. And in case of Log Scaling of outputs, no 0 values are used. | | Reduce trailing |

Sometimes observed concentrations end with several trailing .L.L.O.Q values.
In particular when only the Observed data below LLOQ is transformed, those trailing values should be reduced because the ratio between untransformed simulation values and transformed observed values can become large and cause trouble for Log scale outputs.

| {% hint style="warning" %} If in Observed Data LLOQ values are contained as 0 values, for **Remove data below LLOQ** the option Always should be used. Otherwise, those values can distort the optimization results, because log(0) resp. log(eps=10E-20) is evaluated in the residual calculation and these single residuals may dominate the whole optimization. {% endhint %} **Transform data below LLOQ** | | | | ----------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Observed data and simulated data below LLOQ set to LLOQ (default) |

Observed data and simulation data are transformed consistently to avoid artificial residuals, especially for log scaled outputs.
Values below LLOQ are set to LLOQ to avoid discontinuity for values little above and little below LLOQ.

| | Observed data below LLOQ set to LLOQ/2 | This option is left for backward compatibility. Here, simulation data below LLOQ is not transformed in residual calculation in contrast to observed data. | ### Optimization Algorithms The three available optimization algorithms have specific advantages and disadvantages. While for simple optimization problems (e.g. 1 - 3 Identification parameters which are well informed by sufficient and not contradicting observed data) each of the algorithms works stably and fast, there can be big differences in applicability, robustness and performance in more complex situations. In such cases, some optimization experience is often required. The descriptions and hints given here can only give some basic support, for more detailed information follow the references. {% hint style="info" %} We recommend the following general approach: {% endhint %} 1. You should start with the Levenberg-Marquardt algorithm and the option Standard (= single optimization run) which are the default settings. 2. If the result of a Parameter Identification is not satisfying, choose one of the following options: * In case you do not have enough time and/or hardware resources available, switch to Monte-Carlo algorithm and the option Standard; Afterwards, you may perform an additional Levenberg- Marquardt run using optimal parameter values produced by Monte-Carlo as the new start values. * Otherwise (enough time and hardware resources): perform parameter identification using Levenberg-Marquardt algorithm with option Multiple optimization. #### General hints * Levenberg-Marquardt algorithm is faster than Monte-Carlo algorithm. However, it is susceptible to being trapped by local minima. * Using Levenberg-Marquardt algorithm: sometimes increasing the value of **Finite derivative step size** parameter (e.g. setting it to 1e-4 or 1e-3) might improve the result of parameter identification. * Using multiple optimization (along with any algorithm): if some single optimization runs fail with **Out of memory** exception: reduce the value of **Max. number of processors to use** program option. You can find it under Utilities/ Options (both PK-Sim and MoBi #### Monte - Carlo In each iteration, every free parameter value is separately varied one step upwards and one step downwards from its current value and the objective function is calculated. If the objective function improves (residual sum of squares becomes smaller), the variation is accepted. Here, the variation order is a random permutation. The variation steps are taken at random within in the given parameter intervals and the probability for a step near to the current parameter value is higher than for a step far from the current value, corresponding to the projection grade parameter (alpha). When a parameters variation shows improvement, its projection grade is decreased, otherwise it is increased. This iteration is performed until the break condition holds. **Algorithm parameters** | | | | ---------------------------------------------- | ----------------------------------------------------------------------------------------------------------- | | Break condition for relative error improvement | Termination occurs when the relative improvement of the error evaluation is less than the break condition. | | Scale of projection degree (alpha) | Start value for projection degree. Termination occurs when the minimal alpha is larger than 10 times alpha. | | Maximum number of iterations | The maximum number of iterations performed. | #### Levenberg - Marquardt For a description of this algorithm see Henri P. Gavin: "The Levenberg-Marquardt method for nonlinear least squares curve-fitting problems" (May 2016) () K. Madsen, H.B. Nielsen, O. Tingleff: „METHODS FOR NON-LINEAR LEAST SQUARES PROBLEMS” (2nd Edition, April 2004) () **Algorithm parameters** | | | | ------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Relative chi- square convergence criterium (ftol) | Termination occurs when both the actual and predicted relative reductions in the sum of squares are at most ftol. Therefore, ftol measures the relative error desired in the sum of squares. | | Relative parameter convergence criterium (xtol) | Termination occurs when the relative error between two consecutive iterates is at most xtol. Therefore, xtol measures the relative error desired in the approximate solution. | | Orthogonality convergence criterium (gtol) | Termination occurs when the cosine of the angle between fvec and any column of the jacobian is at most gtol in absolute value. Therefore, gtol measures the orthogonality desired between the function vector and the columns of the jacobian. | | Initial step bound factor | Used in determining the initial step bound. This bound is set to the product of factor and the euclidean norm of diag\*x if nonzero, or else to factor itself. In most cases, factor should lie in the interval 0.1, 100. 100 is a generally recommended value. | | Maximum number of iterations | The maximum number of iterations to perform. If the number of calculation iterations exceeds MAXITER, then the algorithm returns. If MAXITER = 0, then the algorithm does not iterate to adjust parameter values; however, the user function is evaluated and parameter errors/covariance/ Jacobian are estimated before returning. | | Maximum number of function evaluations | Termination occurs when the number of calls to objective function is greater or equal this value by the end of an iteration. | | Finite derivative step size (epsfcn) | Used in determining a suitable step length for the forward- difference approximation. This approximation assumes that the relative errors in the functions are of the order of epsfcn. If epsfcn is less than the machine precision, it is assumed that the relative errors in the functions are of the order of the machine precision. | #### Nelder - Mead This algorithm does not use the defined bounds defined for the Identification Parameters. For a description of this algorithm see Nelder, John A.; R. Mead (1965). "A simplex method for function minimization". Computer Journal 7: 308–313 **Algorithm parameters** | | | | --------------------- | ------------------------------------------------------------------------------------------------ | | Convergence tolerance | Relative convergence tolerance | | Maximum evaluations | Termination occurs when the number of calls to objective function is greater or equal this value | ### Variation of calculation methods and multiple optimizations #### Multiple optimization As explained above, optimization results can depend on the start values, if different local optima exist. This can happen for instance, if more identification parameters are selected and the observed data is heterogeneous. In such situations performing multiple optimization with randomized start values (randomly chosen from the range defined for the Identification Parameters) can lead to different results. Results can compared manually by the global error. If multiple optimizations all return the same result, this is more likely a global optimum. Depending on the number of processors in your computer and the corresponding setting in the General Options (Menu Utilities), optimizations are performed in parallel. #### Calculation Methods Variation In PK-Sim® often it is not clear, which Calculation Method is most appropriate to fit given observed data. Using the **Calculation Methods Variation** you can optimize simulations for different calculation methods e.g. for the Partition Coefficients, and compare the results. ![Configuration of Calculation methods variation](/files/-LNl8bKm2rlhAYF8L-sE) If you have more than one molecule, you can decide whether the calculation methods should be **All the same** for all molecules or if different combinations of molecules and calculation methods should be tested. Also, here optimization are done in parallel as long as processors are available to the Open Systems Pharmacology Suite. ### Display of intermediate and final results #### Visual Feedback During the optimization run, you can view intermediate results. Click **Show Visual Feedback** in the Ribbon bar **Run & Analyze**. A new window is displayed. ![Parameter Identification - Visual Feedback data](/files/-LNl8bKpUz3TYylQXb9d) In this window the status of the optimization run is displayed and a table with the best and currently tested Identification Parameter values and the resulting total error. The error history is displayed in a chart. You can use this information to stop the optimization run manually in certain situations and to assess if the optimization run had decreased the error substantially. In the lower area you can select an output mapping and the current comparison between simulation and observed data values is displayed. You can click the button **Parameters History** to export a table with all parameter value vectors tested during the optimization . And you can export the error history to Excel by right click into the chart. You can use this information for evaluation of the solution path, e.g. to assess the sensitivity of parameters. In case of **Multiple optimization** or **Calculation Methods Variation** the Visual Feedback window gives an overview about the status of the different optimizations. You cannot switch to the detailed Visual Feedback view here. ![Visual Feedback of Calculation methods variation](/files/-LOWPzayndBTXezMtuZF) ### Results of Parameter Identification After the optimization run is finished, you can view the results in the tab Results. Status, elapsed time, number of evaluations and the resulting total error are displayed in the upper table. Below, you find a table with the optimal values, start values and ranges for all Identification Parameters. You can copy and paste both tables for documentation of the results e.g. to the Working Journal. ![Parameter Identification - Results data](/files/-LOWPzaWAdk4QqdM5a77) In case of **Multiple optimization** or **Calculation Methods Variation** you can compare the identified parameter value vectors and total errors for different Calculation Methods or Start Values in the tab Results. ![Result of Calculation methods variation](/files/-LOWPzb2874-spDp6thU) ### Analyses From the ribbon Run & Analyze you can select different charts to analyze the optimization result and assess its quality. #### Time Profile For the different outputs, simulation and observed data values are displayed in different colors. ![Parameter Identification Analysis - Time Profile](/files/-LOWPzb4aXSUWO9M9Pu5) #### Predicted vs. Observed For each observed concentration value a point is plotted with observed value as x-Value and corresponding simulation value as y-Value. ![Parameter Identification Analysis - Predicted vs. Observed](/files/-LNl8bL5V2rGxEDT76Ax) In case of different dimensions of the outputs you have to switch the x-Axis dimension to see the respective outputs. **Adding Deviation Lines to the plot** In a *Predicted vs. Observed* plot the user can right click on the chart and add deviation lines: ![Add Deviation Lines Context Menu Entry](/files/H4NpCLb5hr7ZxUE3llLB) This opens a dialog where the user can specify the fold value of the deviation curves. ![Deviation Line Dialog for specifying the fold value](/files/meOKvckPZLj9TnXvEj7r) This will create two deviation lines according to the given x-fold value which has to be greater than 1. An x-fold deviation range includes simulated values within x-fold and 1/x-fold of observed values. ![2-fold Deviation Lines](/files/vfLwhn7oGZJyUiQPlZqp) In the Chart Editor the deviation lines are grouped under the Category Identity. #### Residuals vs. Time This chart is similar to the Time Profile chart, but on the y-axis the (absolute) residuals used in the optimization are plotted. The chart includes scaling, weights and LLOQ usage and the values are dimensionless, so you can assess the actual influence of the observed data. ![Parameter Identification Analysis - Residuals vs. Time](/files/-LOWPzb8V9xSAcHaGh6O) #### Histogram of Residuals Using this chart, you can check if the residuals are distributed normally - the normal distribution is indicated by the black curve. Strong deviations from normal distribution indicate that the scaling of the parameters may not be appropriate or the model does not reflect the observed data. ![Parameter Identification Analysis - Histogram of Residuals](/files/-LOWPzbAJugNy2NiZNP6) #### Correlation Matrix Based on the partial derivatives calculated locally at the found optimal parameter values, the **Correlation Matrix** and **Covariance Matrix** give some information about *local sensitivity* of **Identification Parameters**. The correlation between two identification parameters based on the observed data is high (positive or negative), if the entry in the correlation matrix is near to 1 or -1. Entries between -0.5 and 0.5 indicate a low correlation. You can use the correlation information to select the parameters to identify. In general, you will often observe correlations, if you have selected many identification parameters, see for example the results if you add the Specific clearance as an identification parameter. {% hint style="warning" %} Keep in mind that all information in this analysis is calculated only at the optimal values and is not necessarily valid in general. {% endhint %} ![Parameter Identification Analysis - Correlation Matrix for two identification parameters](/files/-LOWPzbCG7i78yBHHgYv) ![Parameter Identification Analysis - Correlation Matrix for three identification parameters](/files/-LOWPzbE16van5Zrr--4) #### Covariance Matrix The Covariance matrix gives additional statistical information and can be used to estimate confidence intervals for the identification parameters. {% hint style="warning" %} Keep in mind that all information in this analysis is calculated only at the optimal values and is not necessarily valid in general. {% endhint %} ![Parameter Identification Analysis - Covariance Matrix for two identification parameters](/files/-LOWPzbGvB_5A06WrcgD) ![Parameter Identification Analysis - Covariance Matrix for three identification parameters](/files/-LOWPzbIzudqLLfwjHTC) ### Confidence Interval From the ribbon Run & Analyze in the ribbon bar **Confidence Intervals** you can select different confidence interval charts to assess the quality of the Parameter Identification results. Keep in mind, that **Visual Predictive Check interval** and **Prediction** interval are only available for measured quantities. {% hint style="warning" %} Even if the curves itself are positive, the lower ranges can become negative. Because negative values cannot be displayed in a log scale chart the curves are not visible then. In that case just switch the scaling for the corresponding y-Axis to linear, which is anyway recommended for fractions. {% endhint %} For more detailed background information about the *confidence intervals*, *model error* and data error see \[[23](/references/references#23)], \[[20](/references/references#20)], \[[2](/references/references#2)]. #### Confidence Interval This chart displays the 95% confidence interval of the *model error*, which is based on the uncertainty of estimated parameters. This uncertainty is based on an estimation of the error between the mean value of used observed data compared with the mean value of the (unknown) total data. ![Parameter Identification - Confidence interval](/files/-LNl8bLJgYZwSNHSWtgD) #### Visual Predictive Check Interval This chart displays the 95% Visual Predictive Check interval, which corresponds to the uncertainty based on the *data error*. The *data error* is the standard deviation of the distribution of the used observed data. {% hint style="info" %} You should check, if the distribution of observed data corresponds to the calculated interval, e.g. about 95% of the data points should lie in the calculated interval and the shape of the interval fits to the observed data. {% endhint %} If major deviations exist, the reliability of the Parameter Identification result is in question. In that case you should consider to * improve the optimization, e.g. by different settings in the tab **Configuration**, * improve the *error model*, e.g. changing weights or scaling of outputs in tab **Data**, * improve the model itself. ![Parameter Identification - Visual Predictive Check interval](/files/-LNl8bLMurmm0RwPcBo3) #### Prediction Interval This chart displays the 95% Prediction interval, which corresponds to the combination of the *model error* and the *data error*. It shows, how much future measured data are expected to differ from the model predictions. ![Parameter Identification - Prediction interval](/files/-LNl8bLOoKjWqFh4ElFu) ## More Features ### Reuse of a Parameter Identification Parameter Identifications are saved in the project files and can be attached to the **Working Journal**. So you can rerun Parameter Identifications after modification of the original simulations as long as used outputs and simulation parameters are kept in the simulation. You can also clone a Parameter Identification by selecting **Clone** in the context menu of a **Parameter Identification** in the **Simulation Explorer**. In the cloned Parameter Identification you may define different Identification Parameters or a different configuration. Sometimes you may have different simulations for the same observed data to compare model alternatives. In this case you can also reuse a Parameter Identification by cloning it. Afterwards, you can replace a used simulation with another simulation (with same or similar observed data, outputs and simulation parameters) by selecting **Replace Simulation ...** in the context menu of the simulation in the Data tab. The mapping definition with weights, the definition of Identification Parameters and the Configuration remain the same as long as the corresponding parameters are available. ### Export of Parameter Identification to Matlab® If you want to use the Matlab® optimization capabilities for optimization, you can export the Parameter Identification to Matlab® by selecting the corresponding entry from the context menu of a **Parameter Identification** in the **Simulation Explorer**. Into the selected folder then are exported: * the simulations as .xml-Files, * the configuration of the Parameter Identification as .xml-File, * a example script for optimization and display of results as .m-File. Before calling that script ensure in Matlab® that the path contains the directory "Open Systems Pharmacology\MoBi Toolbox for Matlab". # Sensitivity Analysis The first two chapters provide a basic understanding of the Sensitivity Analysis tool. In the following chapters you find more detailed descriptions of the features and configuration of the tool. ## Motivation The models built by PK-Sim® or MoBi® depend on a lot of input parameters which are based on literature values, measurements, databases, assumptions. For a given set of input parameters a number of output curves is computed in a **simulation**. Often, those input parameter values are not well known. If experimental data for the outputs are given and the model output does not fit the experimental data, then the values for the input parameters have to be adjusted. Because PBPK models can be complex and contain numerous input parameters, it would be useful to know which input parameters have most impact on the output curves. The Sensitivity Analysis tool provides an answer to this question. For a chosen simulation with selected outputs, the relative impact of selected - or all - input parameters on the PK parameters of those selected output curves is calculated and displayed. In addition, the input parameters can be ranked by their impact on a certain PK parameter of an output. This way, input parameters which have the biggest impact on e.g. the AUC of the Venous Blood concentration of a given drug or on the end value of the fraction excreted to urine. Or from the perspective of PK parameters for outputs: It is calculated how sensitive these outputs are to changes in different input parameters. In addition, for certain PK parameter of an output the input parameters can be ranked by the sensitivity of that PK parameter on the input parameter. The general workflow to perform a **Sensitivity Analysis** for a chosen simulation consists of the following steps: 1. Open the simulation and define the interesting outputs in the simulation setting. 2. Create a Sensitivity Analysis for that simulation. 3. Select the input parameters of interest (can be all parameters) in tab Parameters. 4. If necessary adjust their variation range to appropriate values. 5. Start the Sensitivity Analysis. . 6. View the sensitivity rankings in tab **Sensitivity Analysis** for the outputs to identify those input parameters with the highest impact. 7. View the sensitivity matrix in tab **Results** for all output-PK Parameter combinations and all input parameters for details. In the following, we explain the mathematical background of the sensitivity analysis provided. ## Mathematical background To calculate the sensitivity of a PK Parameter of a certain output = PKj to an input parameter = \[ pi ] * the input parameter is varied/perturbed around the value in the simulation by a (small) change = \[ Δpi ] , * a new simulation is performed for the changed input parameter value (all other input values remain unchanged) * the change of the PK Parameter \[ = ΔPKj ] is calculated as the difference between the values in the new simulation and the original simulation. The sensitivity for the PK Parameter to that input parameter is then calculated as the ratio of the relative change of that PK Parameter \[ = (ΔPKj) / PKj ] and the relative variation of the input parameter \[ = (Δpi) / pi ]: ![Image](/files/-LOWQ5Gcbr29Gw0H3gQw) Thus, the sensitivities are dimensionless quantities. As an example, a sensitivity of -1.0 implies that a 10% increase of the parameters leads to a 10% decrease of the PK parameter value, and a sensitivity of +0.5 implies that a 10% increase of the parameters leads to a 5% increase of the PK parameter value. For reasons of numerical stability, a sensitivity is calculated as the average of several sensitivities based on different variations Δk : ![Image](/files/-LOWQ5Ghw5f1h0DZPlp1) The relative variations Δk are defined by multiplication of the value in the simulation with variation factors. These variation factors are defined by setting two configuration parameters "Number of Steps” \[ = n ] and “Variation Range” \[ = a ] in the following way : For each value of k = 1 ... n, two factors are used: ![Image](/files/-LOWQ5GlPhMupn6FZY6X) and ![Image](/files/-LOWQ5Gp1rFwaghJgVSu) For the default setting n = 2 and a = 0.1, we get 4 variation factors: 1/1.1, 1/1.05, 1.05, 1.1 . ## Selection of interesting outputs for a simulation Outputs of a simulation cannot be changed while creating or configuring the Sensitivity Analysis, you need to decide on the outputs before you create a Sensitivity Analysis. To select the outputs of interest for a simulation, open that simulation and click Define Settings and Run to display the Curve Selection Dialog. ## Creating a Sensitivity Analysis To create a new Sensitivity Analysis, do one of the following * Mark a simulation for the Sensitivity Analysis in the Simulation Explorer and select **Start Sensitivity Analysis ...** from the context menu. * Click **Create** in the ribbon bar **Sensitivity Analysis**. * In the Simulation Explorer, right click the Sensitivity Analysis root node and select **Add Sensitivity Analysis** from the context menu. The Sensitivity Analysis view is displayed and the tab **Parameters** is opened. For a hands on example, open the example project Theophylline.pksim5. You can download the project from . In the Simulation Explorer, mark the simulation "*Kaumeier IV 208 mg fit*" and select **Start Sensitivity Analysis ...** from the context menu. ![Sensitivity Analysis - Tab Parameters](/files/-LOWQ5HAkIoayhFuXldn) In the Simulation Explorer, the Sensitivity Analyses are also displayed in a tree. Using the context menu, you can * rename a Sensitivity Analysis, * clone it in order to reuse the Sensitivity Analysis configuration, * add a Sensitivity Analysis to a Journal page, * delete a Sensitivity Analysis. ## Tab Parameters ### Selection of interesting input parameters You can select the input parameters that are of interest to you and that you want to test in the Sensitivity Analysis in two ways: 1. You can select all input parameters by clicking Add All Constants. Depending on the selection Simple or Advanced in the lower selection list, all parameters in the left list (not only the filtered ones) are tested in the Sensitivity Analysis. You can then remove single parameters by clicking ![Image](/files/-LOWQ5HEVM5EGRUeDHRv). 2. You can select specific input parameter by manually selecting them (multiple selection is possible) and clicking Add. To identify the parameters of interest it can be helpful to reorganize the parameter list view on the left and use column filters or the Find field. ![Selection of interesting input parameters](/files/-LOWQ5HIKZj9DuRUz0Ty) {% hint style="info" %} Be aware that only independent input parameters are displayed and selectable for Sensitivity Analysis, input parameters calculated by a formula cannot be selected. {% endhint %} {% hint style="warning" %} Sensitivities are not calculated for input parameters with initial value = 0 (to prevent accidental structural model changes during sensitivity calculations); if such parameters are selected, they are ignored and not displayed in the results. Parameters that have a table formula are not available for selection. In PK-Sim, parameters which should not be changed are also not available for selection. In MoBi,there are no hidden parameters; thus also those parameters could be selected for Sensitivity Analysis (especially using “Add All Constant parameters” functionality). But sensitivity calculation of those parameters does not make any sense. {% endhint %} You can also select another simulation at the top of this tab. If you have selected parameters already which are not available in the newly selected simulation, a warning pops up. ### Adjustment of variation range See “Mathematical background” for the description of the variation concept in the calculation of sensitivities. On the right side of the tab Parameters, you can adjust the variation parameters **Number of steps** and **Variation range**. You can change the parameters by doing one of the following: * change the parameters individually in each row, * change the parameters in the top area and set the value for all input parameters by clicking **All**, * change the parameters in the top area, select multiple input parameters and set the value for the selected parameters only by clicking **Selection**. {% hint style="info" %} Be aware that the time to compute the Sensitivity Analysis is proportional to the number of simulations \= number of input parameters \* number of steps. So in case of performance problems, think about restricting the tested input parameters or reducing the number of steps. {% endhint %} ## Starting Sensitivity Analysis In the ribbon bar **Sensitivity Analysis**, you can start and stop the calculation of the sensitivities. Click **Show Visual Feedback** to see a progress bar of the simulations calculation. ![Visual Feedback - Progress bar of calculated simulations](/files/-LOWQ5HUhExKR72r8jjR) After the calculation is finished, you can: * switch to the tab **Sensitivity Analysis** to see for a selected PK Parameter a ranking of the input parameters by their impact on that PK parameter. * add additional **Sensitivity Analysis** tabs for other PK parameters by clicking Sensitivity Analysis in the ribbon bar Analyses. * switch to the tab **Results** to see a tabular overview of all calculated sensitivities. ## Tab Sensitivity Analysis Select an output and a PK Parameter for that output. (Normalized PK parameters are not displayed, because they have the same sensitivity as the corresponding non normalized PK parameters.) Then a list of the input parameters with the most impact on that PK Parameter is displayed ranked by their impact resp. sensitivity. ![Ranking of Input paramters by sensitivity](/files/-LNl8QcrJ9xVjchcyQCz) For some outputs not all PK Parameters are reasonable, for instance clearance parameters for Fraction excreted outputs. Then no ranking is calculated and displayed. {% hint style="info" %} For display in the chart, the parameters which contribute 90% of the cumulated sensitivity are determined. To do this the sensitivities are sorted by the absolute values and then they are cumulated in order of their sorting, according to Image with l=1,…,nP (number of parameters) and j index of PK parameter. The cumulated sensitivities as defined above include normalization to the absolute total sensitivity. Therefore, the normalized total sensitivity Stotal = SCum, nP j = 1. The cut-off is defined so that the above cut-off parameter sensitivities capture 90% of the total sensitivity. {% endhint %} ## Tab Results Here, the matrix of all calculated sensitivities is shown. See Warnings in “Selection of interesting input parameters” for remarks which sensitivities are calculated. {% hint style="info" %} Sensitivity values in -1.0e-4 .. 1.0e-4 are displayed as 0 for reasons of clarity. {% endhint %} Rows correspond to the selected input parameters (with values <> 0). Columns correspond to the outputs of the simulation - for each output the reasonable PK Parameters are shown with exception of normalized PK parameters, as they have the same sensitivity as the corresponding non normalized PK parameters. (For example for Fraction excreted outputs Clearance PK Parameters are not reasonable.) You can sort and filter rows and columns to restrict the view to the sensitivities of interest in different ways: * Sort rows and columns by just clicking the sort triangle symbol at the right of the header. * For simple filtering just move the cursor right to the sort symbol of the headers **Parameter**, **Output**, **PK Parameter** and click the filter symbol which shows up. You can select the values of interest in the filter list. ![Image](/files/-LOWQ5HhP4C9BnnefAay) * For more sophisticated filtering, right click the header and select **Show Prefilter**. A dialog shows up, click the + symbol and enter more complex conditions. ![Image](/files/-LOWQ5Hl56As3mqeguMZ) As a result, you get a restricted view of the sensitivity matrix. ![Sensitivity Matrix](/files/-LNl8QczprrsKbyr2cIZ) Alternatively, you can export the full matrix (filters are not used) to Excel by clicking **Export to Excel**. # Import and Edit of Observed Data A generic tool for handling observed data within the Open Systems Pharmacology Suite is used in both applications (PK-Sim® and MoBi®) for importing observed data from Microsoft Excel® or CSV files. ## Supported Formats All files need to fulfil the following pre-requisites: * A file contains one or several sheets with data tables. * Column headers are in the first non-empty row. Each data table: * **must** have at least 2 data columns with numeric values: one column with **time** values and one column with **measurement** values. * **can** have additional data column with numeric values for measurement **error** values * **can** have additional data column with numeric values for the *lower limit of quantification* (**LLOQ**) * It is also possible to provide LLOQ values directly in the measurement column (s. [LLOQ](#lloq) for details) * **can** have arbitrary number of further numeric or non-numeric data columns, which can be interpreted as **meta data** which describes a *data set* (e.g. "Study Id", "Subject Id", "Organ", "Compartment", ...). S. [Data sets](#data-sets) for the explanation how meta data is used to split a data table into different data sets. The order and the naming of data columns is not important: the proper assignment of data columns to *Time*/*Measurement*/*Error*/*Meta Data* will be performed during the [*column mapping*](#mapping-panel) process. However to speed up the mapping process it is advisable to name the columns according to their information (e.g. "Time" for the time column etc.) **Units** of numeric columns (Time/Measurement/Error) can be defined in 2 ways (s. [units](#selection-of-units) for details): * Either as part of the header caption in the square brackets (e.g. "*Time \[h]*"). In this case all values of the data column will have the same unit. * Or in a separate column. If no unit is specified (or the specified unit is not valid or not supported by OSP: it can be set manually during the [*column mapping*](#mapping-panel) process). Some examples: * Minimal possible example: time and measurement columns; units in the same column | Time \[min] | Concentration \[mg/ml] | | ----------- | ---------------------- | | 1 | 0,1 | | 2 | 12 | | 3 | 2 | | 10 | 1 | | 20 | 0,01 | * Time, measurement and error; units in the column header | Time \[min] | Concentration \[mg/ml] | Error \[mg/ml] | | ----------- | ---------------------- | -------------- | | 1 | 0,1 | | | 2 | 12 | 3 | | 3 | 2 | 1,9 | | 10 | 1 | 0,8 | | 20 | 0,01 | | * Time, measurement, error, LLOQ, additional meta data; units in the column header | Time \[min] | Organ | Compartment | Dose | Route | Concentration \[mg/ml] | Error | LLOQ | | ----------- | ----- | ----------- | ---- | ----- | ---------------------- | ----- | ---- | | 1 | Brain | Plasma | 1 mg | Oral | 0,1 | | | | 2 | Brain | Plasma | 1 mg | Oral | 12 | 2 | | | 3 | Brain | Plasma | 1 mg | Oral | 2 | 0,5 | | | 10 | Brain | Plasma | 1 mg | Oral | 1 | | | | 20 | Brain | Plasma | 1 mg | Oral | 0,01 | | 0,1 | | 1 | Liver | Plasma | 2 mg | IV | 0,2 | | | | 2 | Liver | Plasma | 2 mg | IV | 8 | | | | 3 | Liver | Plasma | 2 mg | IV | 2 | | | | 10 | Liver | Plasma | 2 mg | IV | 0,5 | | | | 20 | Liver | Plasma | 2 mg | IV | 0,05 | | 0,2 | * Time/Measurement/Metadata; units in separate columns; LLOQ in the measurement column | Time | Time\_Unit | Organ | Compartment | Concentration | Concentration\_Unit | | ---- | ---------- | ----- | ----------- | ------------- | ------------------- | | 1 | min | Brain | Plasma | <0,1 | mg/ml | | 2 | min | Brain | Plasma | 12 | mg/ml | | 3 | min | Brain | Plasma | 2 | mg/ml | | 10 | min | Brain | Plasma | 1 | mg/ml | | 20 | min | Brain | Plasma | <0,1 | mg/ml | | 0 | h | Liver | Plasma | 0,2 | µmol/l | | 1 | h | Liver | Plasma | 8 | µmol/l | | 2 | h | Liver | Plasma | 2 | µmol/l | | 5 | h | Liver | Plasma | 0,5 | µmol/l | | 10 | h | Liver | Plasma | 0,05 | µmol/l | * Time/Measurement/MetaData; units partly in column headers and partly in separate columns; error unit assumed to be the same as measurement unit | Time \[min] | Organ | Compartment | Measurement | Type | Measurement\_Unit | Error | | ----------- | ----- | ------------- | ----------- | -------------- | ----------------- | ----- | | 1 | Brain | Plasma | 0,1 | Concentration | mg/ml | | | 2 | Brain | Plasma | 12 | Concentration | mg/ml | 2 | | 3 | Brain | Plasma | 2 | Concentration | mg/ml | 0,5 | | 10 | Brain | Plasma | 1 | Concentration | mg/ml | | | 20 | Brain | Plasma | 0,01 | Concentration | mg/ml | | | 1 | Liver | Intracellular | 10 | F\_metabolized | % | | | 2 | Liver | Intracellular | 20 | F\_metabolized | % | | | 3 | Liver | Intracellular | 25 | F\_metabolized | % | | | 10 | Liver | Intracellular | 30 | F\_metabolized | % | | | 20 | Liver | Intracellular | 39 | F\_metabolized | % | | ### Data sets A **data set** describes all observed data which belongs to a combination of all **mapped** meta data columns (s. [Mapping panel](#mapping-panel)). Thus the number of data sets which is created from one observed data table is the same as the number of unique combination of the used meta data. Example: let's assume the observed data table looks like below and *Organ*, *Compartment* and *Route* are all used as meta data during the import configuration process. | Time \[min] | Concentration \[mg/ml] | Organ | Compartment | Route | | ----------- | ---------------------- | ----- | ----------- | ----- | | 1 | 0,1 | Brain | Plasma | Oral | | 2 | 12 | Brain | Plasma | Oral | | 3 | 2 | Brain | Plasma | IV | | 10 | 1 | Brain | Plasma | IV | | 20 | 0,01 | Brain | Plasma | IV | | 1 | 0,2 | Liver | Plasma | Oral | | 2 | 8 | Liver | Plasma | Oral | | 3 | 2 | Liver | Plasma | IV | | 10 | 0,5 | Liver | Plasma | IV | | 20 | 0,05 | Liver | Plasma | IV | Then this data will be split into 4 data sets corresponding to the available combinations of `{Organ, Compartment, Route}`: ![Import result: Observed data sets](/files/-MfhB6ZEBK6W5-F9JI9O) * Data set 1: "`Brain.Plasma.IV`" | Time \[min] | Concentration \[mg/ml] | | ----------- | ---------------------- | | 3 | 2 | | 10 | 1 | | 20 | 0,01 | * Data set 2: "`Brain.Plasma.Oral`" | Time \[min] | Concentration \[mg/ml] | | ----------- | ---------------------- | | 1 | 0,1 | | 2 | 12 | * Data set 3: "`Liver.Plasma.IV`" | Time \[min] | Concentration \[mg/ml] | | ----------- | ---------------------- | | 3 | 2 | | 10 | 0,5 | | 20 | 0,05 | * Data set 4: "`Liver.Plasma.Oral`" | Time \[min] | Concentration \[mg/ml] | | ----------- | ---------------------- | | 1 | 0,2 | | 2 | 8 | ## Import Workflow The general process of importing observed data is outlined here. A detailed description is provided in the following subsections. To import data, you should do the following: 1. Click on "**Add Observed Data...**" in the context menu of "**Observed Data**" in the Building Blocks explorer of PK-Sim® or MoBi®: ![Add Observed Data](/files/-MfhB6ZIMKOctF69MuXh) * In PK-Sim® you can also preselect for which molecule observed data should be imported. For this, click on "Add Observed Data for" and select a molecule from the dropdown list: ![Add Observed Data for](/files/-MfhB6ZMWMk4DodzJy47) 1. Select the input file (see [File Selection](#file-selection)). 2. Specify the **column mapping** (see [Mapping panel](#mapping-panel)), enter all required metadata and set the unit and LLOQ information. 3. \[Optionally] Apply **data filters** to exclude some data sets/values from import (see [Data preview](#preview-of-imported-and-original-data)). 4. Add one or more sheets to the import preview. Sheets that should not be imported can be closed by clicking the "x" or the context menu. 5. \[Optionally] Adjust column mapping and/or data filtering. Upon editing of the column mapping, the data preview is re-interpreted and updated automatically. The configured mapping remains the same for the whole import process, and all the imported sheets will be using the same mapping. If you want to import data with different mappings, you have to do this in separate imports. 6. \[Optionally] Adjust the **naming pattern** of the data sets to be imported. 7. Complete the transfer of the imported data sheets by clicking the import button. ### File Selection To import a new set of data from a file, click on the **Add Observed Data** button in the context menu of the observed data and specify the file to be imported. {% hint style="warning" %} The input file must comply with one of the supported formats. If only one sheet does not comply to any of the supported formats, the file is considered invalid and cannot be imported. The import process is stopped. {% endhint %} {% hint style="warning" %} Both excel file formats (.xls and .xlsx), as well as CSV files (.csv, .nmdat), are supported, and it is **not** required to have Microsoft Excel® installed on your computer. {% endhint %} {% hint style="info" %} By switching the file type combo box value, it is possible to import a comma-separated values file (.csv or .nmdat). For such files, the user is prompted to select the column separator used for parsing. Supported separators are ';', ',', '.', and tabulator. Values can be enclosed in double quotes. {% endhint %} ### Preview of imported and original data After selecting the file, a split window appears (see the screenshot below). The left panel ("*Mapping settings*") is described in detail in the next section ([Mapping Panel](#mapping-panel)). The right panel shows a preview of the imported data file, each tab representing one sheet. ![Importer Window](/files/-MczYyl_zN0sW_0nB0nx) Sheets can be closed by clicking the 'x' or by right-clicking on a tab and selecting one of the options displayed. Closed sheets will not be imported and need not comply with the current data mapping. The user can retrieve all closed sheets of a document by the context menu option "Reopen all sheets". {% hint style="warning" %} If the user closes an already loaded sheet, it will be removed from the loaded sheets! {% endhint %} ![Importer Sheet Context Menu](/files/-MczYylgA8ayLk1_-1Fv) The data preview table offers various possibilities for filtering and sorting the data. One can use the filter symbol in the column header of the data to open the filter menu (see screenshot below). By right-clicking the column name, the user can sort the data according to a specific column or open the 'Filter Editor' to create more sophisticated filters (s. [this tutorial](https://devexpress.github.io/dotnet-eud/interface-elements-for-desktop/articles/filter-editor/examples-of-using-the-filter-editor.html) and [this video tutorial (up to minute 2:55)](https://www.youtube.com/watch?v=A6OgNirrPaE#t=27s) for examples). ![Importer Data Table Column Filter](/files/-MczYylkF9lmGSF42AHP) ![Importer Filter Editor](/files/-MczYylt_chyFArHsY7q) {% hint style="warning" %} By default, the defined filter changes only the **preview** of the data. The user can choose to restrict **importing** to the filtered data by checking the checkbox "Use the filters for importing the data" under the data preview table. {% endhint %} There are two buttons for adding data to the import preview - one for adding the current sheet that the user is viewing and the other to add all currently open sheets of the file. In the latter case, **all** opened sheets need to comply to the current data mapping. On the top-right part of the window, one can see the path of the selected source file and also use the "..."-button to select a new file. Selecting a new file, though, will cause the mapping and loaded sheets to be reset, and the work you have done on the current input file will be lost. ### Mapping panel The left panel of the window displays the mapping of the imported data column to the time, measurement, error values and to the meta data of the observed data sets. The initial mapping is performed automatically upon selection of the file and identification of the format, but it can be overwritten by adjusting the entries. This initial mapping recognizes the settings automatically if the data is structured properly. The discovery of columns occurs as follows: 1. Target data columns (Time, Measurement, Error) are resolved. If the data contains any column with numerical data and a header starting with the target name, the column is mapped. The search is not case sensitive. The following column headers will be recognized as the "Measurement" target data column for example: * "Measurement" * "Measurement (12.02.2021)" * "MEASUREMENT \[MG/ML]" * " measurement old \[old unit] \[mg/ml] " 2. The unit of recognized target data columns are resolved. If the data contains any column with a header starting with the target name followed by "\_unit", the column is mapped as the unit. The search is not case sensitive. The following column headers will be recognized as the time unit for example: * "Time\_unit" * "Time\_unit (12.02.2021)" * "TIME\_UNIT \[MG/ML]" * " Time\_unit old \[old unit] " 3. Meta data columns (Species, Organ, Compartment, Molecule, Molecular Weight, Study Id, Subject Id, Gender, Dose, Route) are resolved. If the data contains any column with a header starting with the target name, the column is used for such a mapping. The search is not case sensitive. The following column headers will be recognized as the "Species" mapping for example: * "Species" * "Species (12.02.2021)" * "SPECIES \[]" * " species old \[old data] " 4. All columns on the data containing numerical data has not been used yet and will be used for any still missing target data column in the order they are (e.g., Example file 3). Consider the following examples: Example file 1. | Organ | Compartment | Species | Dose | Molecule | Time \[min] | Concentration \[mg/l] | Error \[mg/l] | Route | Group Id | a | b | | --------------------- | ------------ | ------- | --------------- | ----------------- | ----------- | --------------------- | ------------- | ----- | -------- | - | - | | PeripheralVenousBlood | Arterialized | Human | 75 \[g] glucose | GLP-1\_7-36 total | 1 | 2 | 0,1 | po | H | 3 | 3 | | PeripheralVenousBlood | Arterialized | Human | 75 \[g] glucose | GLP-1\_7-36 total | 2 | 19 | 0,1 | po | H | 3 | 3 | | PeripheralVenousBlood | Arterialized | Human | 75 \[g] glucose | GLP-1\_7-36 total | 3 | 23 | 0,1 | po | H | 3 | 3 | | PeripheralVenousBlood | Arterialized | Human | 75 \[g] glucose | GLP-1\_7-36 total | 4 | 19 | 0,1 | po | H | 3 | 3 | Results in the following mapping: | Data Column | Mapping | | --------------------- | ----------- | | Organ | Organ | | Compartment | Compartment | | Species | Species | | Dose | Dose | | Molecule | Molecule | | Time \[min] | Time | | Concentration \[mg/l] | Measurement | | Error \[mg/l] | Error | | Route | Route | | a | - | | b | - | Example file 2. | Organ | time (old) | time\_unit (new) | c | | --------------------- | ---------- | ---------------- | -- | | PeripheralVenousBlood | 1 | h | 75 | | PeripheralVenousBlood | 2 | h | 75 | | PeripheralVenousBlood | 3 | h | 75 | | PeripheralVenousBlood | 240 | min | 75 | Results in the following mapping: | Data Column | Mapping | | ---------------- | ------------------------------ | | Organ | Organ | | time (old) | Time | | time\_unit (new) | Column containing unit of time | | c | Measurement | Example file 3. | e | time (old) | time\_unit (new) | c | | -- | ---------- | ---------------- | - | | 75 | 1 | h | 1 | | 75 | 2 | h | 1 | | 75 | 3 | h | 1 | | 75 | 240 | min | 1 | Results in the following mapping: | Data Column | Mapping | | ---------------- | ------------------------------ | | time (old) | Time | | time\_unit (new) | Column containing unit of time | | e | Measurement | | c | Error | {% hint style="info" %} The mapping panel is available throughout the whole import process. If the user changes the mapping, the changes are automatically applied to all data sheets, and the result of the modified mapping is automatically updated. {% endhint %} As shown in the screenshot below, the user gets a view of all the available mappings and can map a column to them. A column can be selected to a mapping only once and will no longer be available on the drop-down menus for other mappings, with one exception: the unit column for the measurement can also be mapped as the unit column for the corresponding error. ![Importer Selecting an Excel Column](/files/-MczYym2_WOip-Bad7Ec) Additionally, for some meta data mappings (e.g., Organ, Species and others), the user can select one option from the predefined ones that come from PK-Sim/MoBi. E.g. for the Organ mapping in the example below user could either map the Organ meta data to the source data column "Organ" or set it to any of predefined values ("*Peripheral venous blood*", ..., "*Spleen*", "*Stomach*"). In the latter case: the selected predefined value will be used as "Organ" for ALL imported data sets. ![List of values](/files/-MfhB6ZXf1rtGgaO7ytb) {% hint style="warning" %} The minimum set of a valid data mapping includes a 'Time' and a 'Measurement' mapping. {% endhint %} For the molecule mapping, a column from the sheet can be selected. Alternatively, the user can select from a drop-down menu of the available molecules from the project or specify a new molecule manually by clicking "Edit manually" under "Edit extra fields". ![Mapping molecules](/files/-MfhB6ZZ1jFNRy_g3LA7) The user can also add one or more '**Group by**'-mappings. Those mappings are used to define *additional* meta data and will be used together with the *predefined* meta data ("*Organ*", "*Compartment*", ...) to break down a single data sheet into multiple data sets as described in [Data sets](#data-sets). ![Add GroupBy](/files/-Mflle6aGpnmNWNKdTEQ) {% hint style="info" %} The mapping can be reset by right-clicking on the mapping panel and selecting one of the displayed options. {% endhint %} ![Observed data mapping context menu](/files/-Mflle6csPxodDiSdk8I) #### Selection of units The units for the mapped columns can either be manually entered or specified by a column. In the latter case, each data point can have a distinct unit but from the same dimension. In the unit dialog, the mode of unit definition can be selected. If the unit is specified as part of the header name (e.g. *Time\[h]*) it is automatically recognized by the importer. The user can edit the unit by opening the dialog in the column "**Edit extra fields**" of the corresponding mapping. ![Setting the units manually](/files/-MczYym7soUXYjomHDiz) ![Setting the units from a column](/files/-MczYymG2ae5PM6B29bP) When setting the unit manually, the user needs to select the dimension first, upon which the unit drop-down menu will be filled corresponding units. #### LLOQ The LLOQ can either be specified from the column of the measurement or from a separate column. In the first case (specified in the measurement column), the LLOQ values in the measurement column must be preceded by a "<", e.g. "<0.2", where 0.2 is the LLOQ value. In the second case (specified in a separate column), the values in the column must not be preceded by "<" or anything else, neither should they have the unit written next to them in the cell: the LLOQ column should just contain numerical values. The unit in this case is always the same as the measurement unit. There can only be one single LLOQ value for every data set. In case there are several LLOQ values defined, the user is warned, and in case the user wants to proceed with the import, the highest of these LLOQs will be assumed for the whole data set. Also in this case, if the user has some values that are preceded by "<" in the measurement column, the whole row of that value will be ignored and no simulation point will be loaded for it, since f.e. "<0.2" is not a numerical value, and the measurement column in this case has to contain only numerical values. When importing the datasets, the measurement values that are below the LLOQ are assigned the value LLOQ/2. For example a value written in the measurement column as "<0.2" will be imported in the data repository with a value of "0.1". This happens only to the values of the measurement that are preceded by "<" (e.g. "<0.2") in case the LLOQ comes from the measurement column, or in case the LLOQ comes from a separate column, just the measurement values that have an entry in the same row in the LLOQ column. #### Configuring the error The error can be set to '**Arithmetic Standard Deviation**' or '**Geometric Deviation**'. Since the geometric deviation is dimensionless, it is not possible to specify a unit for it. Otherwise, the user can specify the unit either manually or by a column. The dimension of the measurement and the error unit, as well as their source (manually entered or specified by a column), have to be consistent. This is checked when loading the sheet, and data with inconsistent dimensions cannot be imported. When the unit is configured as manual input, the user must first select the "Dimension" from the drop-down, and then the corresponding units to this dimension will become available in the "Unit" drop-down menu. ![Selecting Error Type](/files/-MdHe7TOkQjKkmwSzG05) #### Molecular weight Concentration data can be imported either in molar units (e.g. \[µmol/l]) or in mass units (e.g. \[mg/ml]). In order to switch between molar and mass units (e.g. to display the data which was imported in \[µmol/l] in \[mg/ml]) it is required to specify the **Molecular weight** of a data set. This can be done either by mapping of the data set to a molecule or by mapping of the molecular weight to a data column. * If neither **Molecule** nor the **Molecular Weight** are mapped: the molecular weight of all data sets is not set. * If only the **Molecule** (but not the **Molecular Weight**) is mapped to a data source column or is set to specific value: the software (PK-Sim® /MoBi®) will check for each data set if the **molecule with the name assigned to the data set is available in the project**: * If yes: observed data set will be automatically assigned the molecular weight of this compound. * If no: molecular weight of the given data set is undefined. However, if a new molecule with the name assigned to the data set is added to the project later on: observed data set will automatically become the molecular weight of this molecule. ![](/files/-MfhB6Zg1PSSs9nAL_s9) {% hint style="info" %} If molecular weight of the molecule is changed by user: molecular weight of all data sets linked to this molecule via the "Molecule" meta data will be automatically adjusted to the new value. {% endhint %} {% hint style="info" %} If the "Molecule" meta data was not mapped during the import process - it can be done later by editing the meta data of an observed data set. {% endhint %} * If only the **Molecular Weight** (but not the **Molecule**) is mapped to a data source column: the value of the molecular weight is taken from the mapped data source column. * In such a case: mapped data column must contain the **same** molecular weight value for all rows of a data set - otherwise the import is not possible ![](/files/-MfhB6ZjxqAzSM3CTF7G) * If the **Molecule** is mapped to a data source column or is set to specific value and the **Molecular Weight** is mapped as well: * For each data set for which the **molecule name is not available in the project**: molecular weight will be taken from the imported data column as described above * For each data set which the **molecule name is available in the project**: molecular weight from the data column will be compared with the molecular weight of the molecule in the project. If they differ - import is not possible. Otherwise, the data set will automatically become the molecular weight of "its" molecule as described above. ![](/files/-MfhB6ZlTe3u8ZVdiSMv) ### The NaN indicator It is possible to define a specific number (e.g. 99999) as an equivalent of NaN. The value and the importer's action on the occurrence of this value can be defined on the bottom of the left panel. On the input field "NaN indicator" the user can specify the value that should be identified as NaN. This value has to be a **numeric** value - it cannot be alphanumeric. In the drop-down menu below, the user can specify to either ignore the whole row containing the NaN value ("Ignore the row"), or to prevent the import ("Prevent the import"). In this case, a pop-up message appears to inform the user of the existence of a NaN value, prompting him to clean up his data and preventing him from importing. ### Confirmation Tab Data sets can be added to preview by clicking on "**Add current sheet**" or "**Add all sheets**": ![Add data sheet(s) to preview](/files/-MfhB6Zo2MYpxAaYFlGk) When at least one data set has been added to the preview, the confirmation tab "**Import preview**" gets activated. ![Confirmation Tab](/files/-MczYymPIA4vf-d5Fd0k) Here, the user can see which data sets have already been loaded. On selecting a data set, the data are being previewed to the right, both as values and in a chart form. The naming with which the data will be imported can be specified on the left side of the panel. This can be done by manually typing in the "Naming Pattern" input field: The user can type keys that represent the name of a mapping inside of curly brackets {}. This will be replaced by the corresponding value for every individual data set. The user is also free to write text that will then be the same for all the data sets names. Additionally, a drop-down with presets for naming patterns is also available. Alternatively, the "Create naming pattern" collapsible panel can be used. One or more 'Naming Elements' can be selected from the list, along with a separator that will be used between these elements. By clicking "Add keys", they are added to the naming pattern. The import can be finalized by clicking on the **Import** button. ## Saving the configuration By clicking the "**Save configuration**"-button, the user can save all configuration settings to an .xml file. This configuration includes the mapping, the NaN preferences, the selected sheets, the path to the selected file and all the other information that can be configured in the importer (data filters, naming pattern, ...). The saved configuration can be used to resume the configuring at a later time point or to import a different file that should be imported with exactly the same configuration. ![Save/Load configuration](/files/-MfhB6ZrvBFXM8-CjJkt) {% hint style="info" %} If some sheets have already been loaded, this state is also part of the configuration. {% endhint %} ## Loading the configuration The user can also load a saved configuration. Clicking the "Load configuration" button will open a "File Selection" menu where the user can select a previously saved configuration .xml file. The settings of that configuration are then applied to the current import process. If something is missing, for example, a column was mapped in the configuration but does not exist in the file the user is trying to load now, the user will receive a warning that this mapping could not be found and will be ignored. {% hint style="info" %} Missing columns will be ignored. {% endhint %} ## Editing Observed Data Once a repository of observed data is imported, it can be manipulated by adding new data points, numerically changing data points or changing metadata. Changes are reversible through and will be tracked in the project history. Numerically changing a value is reflected in real-time in the preview graph below and will result in moving the data point in the data grid to the new settings. The editing window can be accessed by double-clicking the observed data in the building block view or through the context menu. {% hint style="info" %} All values in the time column must be unique in an observed data repository. {% endhint %} {% hint style="info" %} **Editing All Meta Data** Using the context menu of the **Observed Data** folders, the metadata values can be accessed and changed. This is very useful to supplement metadata or to re-organize data. Changes will be applied to all data tables in that folder. {% endhint %} ## Update Observed data Using the context menu on a single data set, the user can update **all data sets which were imported together with the selected one**. ![Update previously imported data sets](/files/-MfhB6ZtPpN---FPZbnh) Upon selecting this option, the user is prompted to select the file from where the data will be re-imported (This can also be the same file used for the original import, just with edited data.) A window appears, showing the changes this re-import would make to the observed data: which data sets will be deleted, which will be overwritten and which will be newly imported. The user can then decide to proceed with the reload or abort it. ![Reload summary](/files/-MdLXBl5mGR5XGylUA5i) {% hint style="info" %} Reloading previously imported data will always update **all** data sets which belong to the same import process. This also means that data sets which are not available in the new data source anymore will be automatically deleted from the project. If this is not possible (for example because a data set is used in a parameter identification or in a simulation) - the update is not possible and the user is prompted to remove such a data set from all simulations/parameter identifications/... **manually**. After that, the update process can be started again. {% endhint %} # Default, Display and Base Units The modeling tools PK-Sim® and MoBi® deal with a variety of physical quantities. Each quantity is related to a physical dimension. This dimension is displayed in a display unit, the preferred display unit is called default unit. Display units can be chosen for a dimension in a project and for a user. In addition, a default display unit for each dimension can be defined. The settings are applied in the following order: * Project Display Units * User Display Units * Default Display Units ![Use the Display Units toolbar in the Modeling and Simulation tab to define display units for projects and for a user](/files/-LOWQ3AGkSbk2hcK5lxr) The upcoming view is similar for both, display units in a project and for a user. ![Choose the display unit for a dimension from the dropdown menu](/files/-LOWQ3AJ-qV0b6p2yW_0) Units can be saved and loaded to and from a xml file. New display units can be added using the **Add Unit** button and filling up the new entry in the unit table. In addition, default display units for each dimension can be defined in the **User Settings** in the **Options** toolbar. When a new entity (parameter, molecule, ...) is created, the default display unit is used automatically. ![Define the default display unit for a dimension in the User Settings](/files/-LOWQ3ANxdjQUxTDyOWK) If you want to update all display units to the default units, use the **Update all Display Units** button. This action will not change the value of a dimension. {% hint style="info" %} If a view is open while reverting all units to the default settings, it might be required to close the view and open it again to verify that display units are set back to default settings. {% endhint %} Internally, the values for all quantities of a certain dimension are stored and calculated in the same unit, the so called **base unit** of that dimension. You find an overview of all dimensions with their base units in the appendix. The base units are consistent since version 3.2.1; when you want to work with projects stored with previous versions, where you have used manual conversion factors in formulas, please refer to “Conversion of MoBi® 3.1 projects in MoBi® 3.2” # Working Journal ## Project Documentation The Working Journal allows for easy documentation of your working process with the Open Systems Pharmacology Suite. Because building PBPK and PD models is often a complex process, a documentation is necessary * for the modeler to remember the model building process, * for people who take over a model, * for authorities who have to evaluate the quality of modelling results. Although it is possible in principle to use any text editor to write a documentation, the Working Journal provides several features, which give additional benefit: * Integrated rich text editor with the essential formatting options, * Easy transfer of Open Systems Pharmacology Suite content to the Journal (tables, charts), * Storage of simulations or building blocks as attachments to Journal Pages which can later be compared to other simulations or even reloaded, * Fast full text search in the complete Journal, * Journal Diagram as graphical overview of the model building process, A Working Journal can be shared among several PK-Sim and MoBi project files, so one unique journal can be used within your project even if you use different project files. Even different users can access the same Working Journal at the same time - but only one user can edit a Journal Page at a time. From the technical point of view, the Journal consists of a .sbj file which contains all content, attachments and meta information. After each important workstep, intermediate results or decision points can and should be added a Journal Page to the Journal. This should include the result, the input values, and description of decisions. For instance, the values of the favorite parameters and result charts can be copied into the Working Journal by copy & paste and corresponding simulations and building blocks can be attached to the Journal Page directly from the context menu. ## Overview To access the Working Journal, select the Tab Working Journal. Most buttons are deactivated before having created or selected a Journal for the current project file. ![Journal Ribbon](/files/-LNl8RobK1KbFDU9EdU0) To add the first Journal Page, click **Add Page**. You are asked, whether you want to open an existing Journal or to create a new one. * If you have already created a Journal for the project (NOT project file), click Open and select the .sbj file. * Otherwise, click **Create** and select a location and enter a file name for the .sbj file. A Text Editor opens, and here it is possible to * edit the Title of the Journal Page, which is also visible in the Journal View (see “Journal view”), * enter and format text like in other text editors (you can also insert pictures or symbols, create tables, use hyperlinks etc.), * tag your document with keywords, e.g. the project file name, which can later be used for filtering. The Page is saved automatically, when closing the Editor or switching to another Page. Additionally, you can save any time explicitly using the short cut CTRL-S or the corresponding button in the file menu. ![Journal Editor window](/files/-LNl8RodnHos1nA9ZOyI) ### Journal view On the right side of the PK-Sim or MoBi application, the **Journal view** is shown by default. You can show and hide it like other views. In case you have removed the view, you can reopen it by clicking the corresponding button in the Tab **Views**. ![Image](/files/-LNl8RohImw4DGou7sJj) By default, the Journal pages are ordered by the creation date in a descending order. For each page, the unique index, the title, creation date, tags and the first characters of the text are displayed. You can select other columns with the column chooser to display for example the userid of the author. You can use the columns for sorting, filtering and grouping. This is helpful in particular in large projects, where different authors contributed or different project files are used. To open a Journal Page in the Editor or to bring the Editor on top of the other windows, just double click on the corresponding Journal Page row. Alternatively, you can use the context menu (by right click) to edit or delete a Journal Page. With a single click on a Journal Page row, you activate the Journal Page without bringing the Editor on top. At the bottom of the **Journal View**, some detail information is displayed for the selected Journal Page, in particular a list of related items, if you have attached e.g. simulations or building blocks. ### Journal Ribbon group After you had selected a Working Journal for your project file, all buttons in the Journal Ribbon group are active. ![Image](/files/-LNl8RojGt4ksbRmLFjJ) In the following sections we describe the available functions. #### Add Page A new Journal Page is created and displayed in the Journal Editor. Changes in the previously edited Journal Page are stored. #### Journal Editor The Journal Editor is opened on top of other windows, if you have closed or hidden the Journal Editor. Only one Journal Editor window is open at the same time. #### Search The search area is opened in the Journal view. See “Searching the Journal” for more information about searching in Working Journal. #### Export Journal The currently filtered subset of Journal Pages in the Journal View is exported to a .docx Document. This function allows you to export the complete Journal or a subset. If you would like to distinguish between public and internal Journal pages, you can use corresponding tags for example. #### Refresh Journal The current changes in the Journal Editor are saved and displayed in the Journal view. Moreover, changes in the Working Journal made by other users are reflected in the Journal view. Keep in mind that a Working Journal can be shared by different project files and so different users can use the same Working Journal simultaneously. #### Select Journal A file selection dialog is opened, which allows you to select another Working Journal .sbj file. This is usually not necessary, only in case you have selected the wrong Working Journal before. ## Adding content to a Journal page Besides manually entering content into a Journal page, you can copy and paste tables and charts from PK-Sim or MoBi. So you can for example copy the Favorites table and the simulation chart within seconds to a Journal page and in this way document input and output of your model. {% hint style="info" %} It is recommended to select all parameters under consideration as **Favorites** and to document the source of all parameter values changed from the default in the column **Value Description**. This ensures a comprehensive overview of the essential input of your simulation which you can document by copying just the Favorites table. {% endhint %} ### Copy & paste of tables You can copy tables or selection of rows to a Journal Page. In both cases only the visible rows and columns are copied. So you can use the sorting and filtering features of the table to restrict the transferred table content. You can also remove a column by just dragging the column header out of the table area. To copy the visible table into the Working Journal, do the following: 1. Right click into a row header (on the left of a row) and select * Copy Table - to copy the whole visible table - or * Copy Selected Rows - to copy all selected rows (you should have selected rows before by SHFT + Click or CTRL + Click) 2. Switch to the Journal Editor, move the cursor to the intended position and select Paste from the context menu (by right click). Alternatively, you can paste the tables also to other tools like Powerpoint® or Excel®. ![Copy and paste a Table](/files/-LNl8Rol8fvgv1Yq9YvT) {% hint style="info" %} Use short cuts for copy (CTRL+C for Selected Rows, SHFT+CTRL+C for whole table) and paste (CTRL+V). {% endhint %} ### Copy & paste of charts You can copy charts in standard size independent on the size of the application window. To define the chart size and also font sizes open in the **Chart Editor** the Tab **Chart Export Options** and define the properties. To copy the chart into the Working Journal, do the following 1. Right click into the chart area and select **Copy to Clipboard**. 2. Switch to the Journal Editor, move the cursor to the intended position and select Paste from the context menu. Alternatively you can paste the tables also to other tools like Powerpoint® . ![Copy and paste a Chart](/files/-LNl8Ron4r2U7JOZWHKW) ## Working with Related Items Additionally to the content written and copied in a Journal Page, you can attach Simulations and Building Blocks to a Journal Page as **Related Items** to save the current state of your work. For example, you create a Journal Page to document the working state at some milestone presentation and attach the simulations used. Later, you can easily compare current simulations to those milestone simulations and identify differences. Or you can even reload the simulation in its old state and rerun it with a changed parameter value. (Reload of a simulation in MoBi results in loading missing Building blocks, too - in PK-Sim only the simulation itself is reloaded.) To attach a Simulation or a Building Block to the active Journal Page, just select the context menu entry **Add to Journal ...** at a Simulation or Building Block in the respective Explorer view. The Simulation or Building Block is then displayed in the **Related Items** list at the bottom of the Journal view. ![Image](/files/-LOWQ4xdpf1AftHsj4Xx) Using the icons on the right of a **Related Item** you can * compare the attached Simulation or Building Block to one of the current Simulations or Building Blocks of the project, * reload the attached Simulation or Building Block into the project using a unique name, * delete the **Related Item**. ## Searching the Journal After you documented your project work using the Working Journal, you might want to use these "memories". To do so, you can use the meta data like Title, creation date or tags to find the Journal Page you are interested in. But often it is easier just to search for a specific keyword or phrase you used in your documentation. To search for a word or phrase do the following: 1. Click the Search button in the tab **Working Journal** to open the Search area in the **Journal view**. 2. Enter the phrase into the Search field (or select one previous search phrase from the list you get by clicking the ![Image](/files/-LNl8Rouah4ksBElrXKP) button at the right of the Search field). If necessary, open the Search Options by clicking the ![Image](/files/-LNl8RowWOz9ncVOoo-b) button and select options. 3. Click on the **Find** button. 4. A list of Journal Pages which contain the search phrase is displayed. For each Page the matches are displayed in the context. Double click on a Journal Page to open the Page in the Journal Editor - the **Find Dialog** of the Editor is displayed automatically; so you can browse through the find results in the Page. (A direct navigation from the match in the Journal view is not possible.) ![Image](/files/-LNl8Royy-TLtnmLa6M6) Click the ![Image](/files/-LNl8Rp-CqwjlHm35HCp) button on the left of the Search field to close the search area. ## The Journal Diagram The modelling process in PBPK/PD projects is often not straight forward but requires consideration of different alternatives and testing of several approaches. So the working process is mostly not represented appropriately by just a sequence of work status. Instead, it looks like a tree with several dead ends and one path to the final solution. Using the **Journal Diagram**, you can visualize your working process in a more appropriate way to maintain an overview of complex projects. You can use this overview for yourself or export it to project reports or slides. You can also see the Journal Diagram as a "diagram of content" of your Working Journal. You can find the Journal Diagram at the bottom of your PK-Sim or MoBi window. It is hidden by default. If you have removed the view, you can activate it using the button Journal Diagram in the Tab Views. There is only one unique Journal Diagram per Working Journal. ![Image](/files/-LNl8Rp3SEFJZOsRBLDF) The Journal Diagram displays green rectangular nodes for each Journal Page and blue circle nodes for each attached related item at a Journal Page. You can arrange the nodes as you like just by drag & drop. If you move a Journal Page node the connected Related Item nodes are moved, too. The green links represent predecessor-successor (or parent-child) relations in your working process. While a Journal Page representing a work status can have several successor Journal Pages, it can have only one predecessor Journal Page. To connect two Journal Pages, do the following: 1. click on the right connection port, 2. hold the mouse key and drag to a left connection port of another Page, 3. release the mouse key. To delete a connection, select it and press the DEL key. After you have arranged the Journal Diagram, click the Save Diagram button to save the Diagram layout to the Working Journal. {% hint style="warning" %} Clicking on Reset Layout to Default does immediately overwrite your layout work, so be careful using this button. (Result: All Journal Page nodes are displayed side by side in one horizontal sequence.) {% endhint %} You can zoom the diagram like all other diagrams by pressing the CTRL key while moving the mouse wheel. By right click into the diagram area you get a context menu, which allows you to * **Copy to clipboard** the Journal Diagram (and paste it into other applications like Powerpoint® , * Reset Zoom of the Journal Diagram, * Hide/Show Related Items to maintain the overview in large diagrams. # History Manager and History Reporting ## Logging, undoing, and re-doing user actions The history manager serves two purposes. On the one hand, it allows you to precisely log, and thereby document, all steps that lead to a particular result. This log can be saved to disk as an Excel® report. On the other hand, with the history available, the user can step back in the history to any previous state of the current session, and take that as starting point for a different direction in model development. ![History manager, and history related ribbon groups in PK-Sim®](/files/-LNl8PvlzYJHLFh2XfO2) The history manager is available both in PK-Sim® and MoBi®, with only minor differences between the two programs. It is located at the lower part of the application window screenshot above. If it is not apparent, look for the little handle on the lower left corner which can be used, by hovering over, to pop up the history manager. Use the top right controls (in this history window) to make the history permanently visible. Other elements of relevance for interaction with the history are placed in the "Modeling & Simulation" ribbon as Buttons: * Undo * Add Label... * Create Report The history manager itself presents a table view of the history. Each line of the history describes a specific *state* of the project that was arrived at after a user interaction. The topmost state in the list is the current state of the project. Each line has several columns that describe the state, with small differences between PK-Sim® and MoBi®: ### PK-Sim® * State After Action: The number of the state of this history line * Building Block Type: Which building block *type* was affected by the associated action * Building Block Name: Which building block name was affected by the associated action * Command Type: The particular command of this state * Object Type: A building block may be composed out of different objects, it is mentioned here which type was affected * Description: What was done in this action. This columns deserves your main attention * User: Since a project may be edited by several users, the user that caused this item is listed here * Time: Date and time of the action ### MoBi® * State After Action: The number of the state of this history line * Command Type: The particular command of this state * Object Type: An object type may be a building block, a reaction, a formula, or something else. Here, the particular object type that was affected is listed * Description: What was done in this action. This columns deserves your main attention * User: Since a project may be edited by several users, the user that caused this item is listed here * Time: Date and time of the action {% hint style="info" %} Like most tables in PK-Sim®, the history table view can be sorted and filtered by *any* column. The column can be used for sorting by clicking on the column header. When hovering over the column header with the mouse, you can see a little funnel symbol: By clicking on the funnel a list with all entries in that particular column is shown. You can select one of the entries and the table will be filtered to show only rows containing that entry in the column. {% endhint %} The following sections describe the use of the history manager for a) navigating in the project history, b) adding labels and comments to the history, and c) exporting the history as a report. ### Undo and rollback: Navigating through the history As known from other applications, user interactions of the current session can be un-done: The history manager has a "Rollback..." button and an associated numerical field. Within the history manager, the history list displays all previous user actions. You can select an entry in this list. The entry is numbered, and the number appears in the numerical field. You can click the "Rollback..." button, and this will undo all actions that were performed after the respective step and revert the state of the project to that numbered state. {% hint style="info" %} Please note that by using the rollback function all intermediate steps will, nevertheless, be conserved and can be restored. However, in contrast to the undo functionality, simulation results will not be reconstructed and it is required to re-run the simulation. {% endhint %} PK-Sim® offers an additional way to achieve this: The "Modeling & Simulation" ribbon has a ribbon group History that offers a button "Undo". By clicking this button, you undo the last action. A second click on this button will undo the undo - that is reverting to the original state. ### Labels and comments At any stage, the current stage of the application can be labeled. The History Manager provides an button "Add Label...". When clicking on this button, an "Add Label..." window appears and allows you to add a label and a comment. This label will appear in the history manager and be time stamped with the current date and time. Labels are always applied to the *current* state of the project. In addition, the history manager provides an button, "Edit Comments". This can be used to add a comment to the currently selected entry of the history. If a comment already exists, it can be edited. Comments of a label can be edited as well. In PK-Sim®, the "Add Label..." and "Edit Comments" functionality is additionally available as buttons in the "Modeling & Simulation" ribbon. ### Exporting the history The "Modeling & Simulation" ribbon provides a "Export History" button. When clicking on this button and selecting "Export history to Excel®", a file save dialog appears. Please choose a location and name for the file. The file will be saved in Excel® format and opened in Excel® after saving is complete. # Setting up a Drug-Drug Interaction in PK-Sim Inhibition of a metabolizing enzyme or transporter by a drug can be defined directly in PK-Sim® in a simple and user-friendly manner. In the example workflow below, a drug-drug-interaction (DDI) model is set up using preconfigured templates compounds, e.g. the drug itraconazole, its metabolite hydroxy-itraconazole, and midazolam. Load the predefined compound from templates into PK-Sim® by clicking on the **Compound** icon in the **Load Building Blocks** menu of the **Import/Export** tab. ![Load predefined compounds templates to ease set up of a DDI](/files/-LNl8QNHAY7yS4gdme9m) In this case, the preconfigured itraconazole compound building block is imported. ![Itraconazole is a predefined compound](/files/-LNl8QNMYC16EIppkVic) In the predefined compound Itraconazole, Hydroxy-Itraconazole is already pre- specified as primary metabolite. However, users can make changes to all fields if desired and well-founded. ![Metabolite Hydroxy-Itraconazole is predefined for Itraconazole](/files/-LNl8QNP6C_cki4En2WY) Process type and Ki values of the inhibition have already been pre-specified for the template compounds Itraconazole and Hydroxy-Itraconazole: ![Process type is predefined for Itraconazole/Hydroxy-Itraconazole](/files/-LNl8QNSNTjzsNW6Wz5x) Next, expression levels of metabolizing enzymes can be added to the **Individual** building block to be used in the simulation: ![Expression levels of enzymes needs to be specified](/files/-LNl8QNWpurm-QMtfUh8) Further building blocks can be defined in the respective sections and a simulation is then created by clicking on the **Create** button in the **Simulation** section in the **Modeling and Simulation** tab. In the pre-configured compound templates, the inhibition processes for each enzyme or transporter are predefined, but can be adjusted by the user if applicable. Enzymes present in the **Individual** building block are matched with processes specified in the used **Compound** building blocks and metabolites are defined. Also, systemic processes regarding transport or excretion (e.g. ‘Glomerular Filtration’ like in the example displayed here) are shown and can be modified as desired. ![Processes associated with Itraconazole and Hydroxy-Itraconazole in the pre- defined template](/files/-LNl8QNZMN4ua1A7itER) In the next step, application protocols for each compound are defined using the available building blocks the user has configured before. ![Definition of administration protocols for each compound from available building blocks](/files/-LNl8QNavmiMjUHmIzR6) After having added and matched all building blocks required, the simulation is set up and can be run by either hitting F5 or using the **Run** button in the **Simulation** section of the **Modeling and Simulation** tab. After running the simulation, all compounds and metabolites (in this case Itraconazole, Hydroxy-Itraconazole and Midazolam) can be plotted and the simulated PK data can be analyzed for each. ![Analysis view of all Itraconazole, Hydroxy-Itraconazole and Midazolam](/files/-LNl8QNcXeeab7xgRkyG) Also, at any given time after the simulation has been created, the simulated metabolic network that was defined can be displayed as a reaction diagram. Like in MoBi®, the blue dot of the reaction triangle connects to the educts of the reactions, the red dot to catalysts (e.g. interacting substances, enzymes or transporters) and the green dot to reaction products as shown below. ![Reaction diagram is the graphical representation of the metabolic network](/files/-LNl8QNeFP_lBfaAD54W) # Qualification ## Qualification framework ### Introduction The qualification framework enables an automated validation of various scenarios (use-cases) supported by the OSP platform. This technical framework is used, for example, to release, in full confidence, a new version of the OSP Suite by verifying automatically that an ever-growing list of scenarios is performing as expected. A **qualification scenario** can be performed after an **evaluation** of the involved PBPK models has been done. A PBPK model evaluation only contains the healthy adult model development, and is divided into the following steps: * PBPK model **development and verification** with observed data * Model evaluation plan generation ("*evaluation* plan" = "*qualification* plan **for one model**") * Evaluation report generation ("*evaluation* report" = "*qualification* report **for one model**") The workflow of a PBPK model evaluation is similar to that of a PBPK model scenario qualification. A qualification scenario can be based on a single PBPK model or several models and is divided into the following steps: * Scenario qualification (**pure predictions**) with observed data (e.g. DDI scenario, Enzyme ontogeny scenario) * Qualification plan generation * Qualification report generation ![](/files/-LsgfnfSWWhg-0qQyOzH) As a PBPK model evaluation workflow is similar to that of a qualification scenario, with the difference being model development and model application, respectively, the focus here will be on the scenario qualification workflow. In a first step, the qualification scenario is saved to a dedicated qualification repository on GitHub. This repository contains a detailed qualification plan that links and combines respective models and data describing the use case to qualify. The qualification plan consists of: * PK-Sim project files (more precisely: PK-Sim project file [**snapshots**](https://docs.open-systems-pharmacology.org/working-with-pk-sim/pk-sim-documentation/importing-exporting-project-data-models#exporting-project-to-snapshot-loading-project-from-snapshot)) * Descriptions of potential cross-dependencies between PK-Sim project files (if adequate) (e.g. it is possible to inherit building blocks or simulation parameters) * Observed data sets (needed for model development and verification) * Qualification scenario description text modules * Detailed report settings related to the generation of charts and qualification measures. {% hint style="info" %} Any file used in the qualification plan (e.g. PK-Sim projects, observed data sets, text modules etc...) can also be saved in an external repository and then conveniently referenced by the qualification plan. {% endhint %} ![](/files/-LsgfnfbpYnXHM5YQJ39) In the next step, the **Qualification Runner** (stand-alone tool) processes the qualification plan, i.e. all project parts are exported and prepared for the **Reporting Engine**. The Reporting Engine provides a validated environment for model execution and generates tables and figures for the final qualification report. This report contains the evaluation of the individual PBPK models with observed data (i.e. standard goodness of fit plot, residuals-vs-time plot, visual predictive checks) and a comprehensive qualification of the specific use case assessing the predictive performance of the OSP suite by means of a predefined set of qualification measures and charts. The automated execution of the described workflow can be triggered to assess re-qualification, for example, when new data is available, after changes in model structure or parameterization, or when releasing a new version of the OSP Suite. Example: **Showcase of predicting cytochrome P450 3A4-mediated drug-drug interactions** ([\[121\]](/references/references#121)) ## Creating a (re-)qualification plan part I Creating a qualification report is similar to writing a scientific article: A report is written and structured in chapters, for example beginning with a short description of the scientific background of the scenario (use-case), followed by a brief methodological description (e.g. modeling strategy, available data used during model building (for model evaluation report), and underlying main assumptions) and the presentation of the qualification workflow results in the third section of the report. The qualification plan orchestrates this process and defines how all the *static* and *dynamic* content will be combined into the final report document. * “*Static content*”: Will be taken AS IS and inserted into the report without any further modifications. * “*Dynamic content*”: Software must actively do something to produce expected results (e.g. create plots). This content may change between OSP versions in case of differences between the previous and new model structures/parameterizations. Technically, a qualification plan is nothing more than a text file in [JSON format](https://en.wikipedia.org/wiki/JSON) (file extension: **.json**). You can use any plain text editor for creating and modification of such a file. However, it is much faster and easier to use a json editor (e.g. the free *Visual Studio Code* (*VSCode*); s. the section [**Creating a (re-)qualification plan part II: Tools**](#creating-a-re-qualification-plan-part-ii-tools) for details). Note that many scripting environments (Matlab, R, etc...) also allow for the comfortable editing of JSON files. ### Components of a (re-)qualification plan ![](/files/-Lsgfng1ByFCufdkZmm-) #### Projects Describes all projects used in a qualification scenario. Currently, only PK-Sim projects are supported. MoBi projects will be supported in the mid-term future. ![](/files/-Lsgfng5Yw4wpboYMAIW) * "**Id**": Whenever a project is referenced within a qualification plan: it happens via its project id. Any non-empty string can be defined by the author of a qualification plan as a project id (the only restriction: a project id must be *unique* within one qualification plan). * "**Path**": path to a project **snapshot**. Can be defined: * Either in form of an URL of remote file (e.g. "**" * or in form of a path to a LOCAL file (given **relative to the location of current qualification plan**), e.g. "*Dapagliflozin-Model/v1.1/Dapagliflozin-Model.json*") * "**BuildingBlocks**": OPTIONAL, may be empty. List of inherited building blocks. The idea behind is: The use-case requires some building blocks (e.g. compound, individual, ...) to be exactly **the same in one or more projects**. Instead of modifying those projects by hand, the qualification plan can automate this action and ensure that building blocks are used consistently. * "**Type**": type of a building block (one of: "*Compound*", "*Event*", "*Formulation*", "*Individual*", "*ObserverSet*", "*Population*", "*Protocol*", "*ExpressionProfile*") * "**Name**": name of a building block (must be the same in both parent and child project) * "**Project**": Id of the parent project **Example** * Individual building block "*Standard\_Adult\_UGT*" in the project "*Mefenamic\_acid-Dapagliflozin-DDI*" will be overwritten by the Individual building block **with the same name** from the project "*Dapagliflozin*" (if there is no individual with the same name in the "*Dapagliflozin*" project: execution of the qualification plan will stop with an error) * Compound building block "*Mefenamic acid*" in the project "*Mefenamic\_acid-Dapagliflozin-DDI*" will be overwritten by the Compound building block **with the same name** from the project "*Mefenamic\_acid*" (if there is no Compound with the same name in the "*Mefenamic\_acid*" project: execution of the qualification plan will stop with an error) ![](/files/-LsgfngRGd39FC99jnwE) * "**SimulationParameters**": OPTIONAL: List of inherited simulation parameters (i.e. parameters that are not specified in building blocks, but in the simulation, e.g. `blood/plasma concentration ratio` or `P (interstitial->intracellular)`). Same principle as in case of inherited building blocks: simulation parameters can be inherited between projects. Each inherited simulation parameter description consists of: * "**Project**": Id of the parent project * "**Simulation**": Simulation name within the parent project * "**Path**": Path to the simulation parameter * "**TargetSimulations**": Simulation name(s) within child project **Example** * In all target simulations of the project *Mefenamic\_acid-Dapagliflozin-DDI* shown below (*DDI Control - xxx, DDI Treatment - xxx*), the value of the parameter `Dapagliflozin|logP (veg.oil/water)` will be set to the value of the same parameter in the simulation `PO SD 10 mg (perm)` from the project *Dapagliflozin*: ![](/files/-LsgfngXfC1yBUw_Mg7z) #### Observed data sets Similar to a project, an observed data set is identified by its Id, which must be unique within a qualification plan. There are two kinds of observed data set: 1. Observed data set which is included into one project used by the qualification plan. This data set can be used in the qualification plan without any further specification. The `Id` is, in this case, the name of the observed data set as defined in the PK-Sim project. 2. Observed data set which is not included into one project. It must be described in the "*ObservedDataSets*" section of a qualification plan. ![](/files/-Lsgfngco3I5mEzdhcwO) * "**Id**": (Unique) id of an observed data set * "**Path**": path to an observed data set file. Can be given as remote URL or local file path (s. the [Projects](#projects) section for details). * "**Type**": type of an observed data set. Can be one of: * "*TimeProfile*". Corresponding observed data set must have the columns with time values, measurement values and (optionally) error values with units (s. also [here](https://docs.open-systems-pharmacology.org/shared-tools-and-example-workflows/import-edit-observed-data)). [Example](https://raw.githubusercontent.com/Open-Systems-Pharmacology/QualificationPlan/7ab7c59dfce9201845ebcd8247b2a5cad344bc03/examples/minimal/reporting%20engine%20input/ObservedData/Itraconazole%20600mg%20MD.csv) * "*PKRatio*". [Example](https://github.com/Open-Systems-Pharmacology/Pediatric_Qualification_Package_GFR_Ontogeny/blob/4e905c62f348a107e3cb96b7fe44c5f8e201da75/input/PK-Parameters.csv). Mandatory columns are: * an ID number to reference to ('*ID*') * PK-parameter value and its unit (e.g. '*AUC Avg*' and '*AUC AvgUnit*' for AUC; '*CL Avg*' and '*CL AvgUnit*' for CL etc.) * the simulation duration ('*t0*' ; '*tend*' ; '*t Unit*'). * "*DDIRatio*". [Example](https://github.com/Open-Systems-Pharmacology/docs/blob/v12/assets/images/part-5/DDIRatio.csv). Mandatory columns are: * a unique ID number to reference to ('*ID*') * a unique descriptive name (i.e. Author Year) ('*Study ID*') * the corresponding victim drug ('*Victim*') * the corresponding perpetrator drug ('*Perpetrator*') * the route of administration (e.g. PO, IV, ...) of the victim ('*Route Victim*') * the route of administration (e.g. PO, IV, ...) of the perpetrator ('*Route Perpetrator*') * the compartment (i.e. plasma, whole blood, etc.), from which the victim drug PK parameters should be assessed ('*Compartment*') * the dose of the perpetrator ('*Dose*') and its unit ('*Dose Unit*') * the observed AUC ratio of the victim expressed as AUC with perpetrator divided by AUC without perpetrator ('*AUCR Avg*') * the observed C\_max ratio of the victim expressed as C\_max with perpetrator divided by C\_max without perpetrator ('*CmaxR Avg*') * the time frame of the simulation without perpetrator, from which the simulated AUC and C\_max of the victim should be calculated ('*t\_placebo\_0*' ; '*t\_placebo\_end*') * the time frame of the simulation with perpetrator, from which the simulated AUC and C\_max should be calculated ('*t\_treatment\_0*' ; '*t\_treatment\_end*') * and the unit of the respective time definitions ('*t Unit*'). Note that observed clearance ratios need to be transformed to AUC ratios before (adding a comment in the '*Comment*' column is recommended). #### Sections Defines the chapter structure of the report. A `section` consists of: * "**Reference**": Unique section identifier. Is referenced in other parts of the qualification plan to define which dynamic content must be added to the chapter (dynamic content will be added at the end of the chapter). Section reference must satisfy the following rules: * Starts with a **letter** (*a-z* or *A-Z*) or a **digit** (*0-9*) * All subsequent characters can be **letters**, **numbers** (*0-9*), **hyphens** (-), **underscores** (\_), and **periods** (.) * Must be different from all other section references AND from all header in one of the static content files * "**Title**": Chapter title * "**Content**": OPTIONAL Path to the **static** content file which will be inserted at the beginning of the chapter. Can be given as remote URL or local file path (s. the [Projects](#projects) section for details). Static content files must be written in [Markdown](#markdown) format (s. below). * "**Sections**": OPTIONAL list of sub-sections. Every sub-section is built in the same way (thus report structure can be defined with an arbitrary chapter depth level). ![](/files/-LsgfngkLSbfy4CwYa2e) {% hint style="info" %} **Markdown** Markdown files are text files in Markdown format (file extension: **.md**). Markdown is a way to style text on the web. You control the display of the document; formatting words as bold or italic, adding images, and creating lists are just a few of the things we can do with Markdown. Mostly, Markdown is just regular text with a few non-alphabetic characters thrown in, like `#` or `*`. Good introductions into the markdown format can be found here: * * You can use any plain text editor for creating and modification of markdown files. However it is much faster and easier to use a dedicated markdown editor, e.g. *Typora* () {% endhint %} #### Intro An (optional) introduction can be added to the report. The differences between introduction and sections are: 1. In the generated report, the introduction will be inserted at the very beginning, before the TOC (table of content) and is not part of the TOC. 2. The introduction does not have any *Reference* and it is not possible to assign any dynamic content to it. The introduction is defined by: * "**Path**": Path to the **static** content file. Can be given as remote URL or local file path (s. the [Projects](#projects) section for details). Static content files must be written in [Markdown](#markdown) format. ![](/files/-LsgfngtdqQvQ0f6W_fb) #### Inputs A convenient way to specify which building blocks and/or simulations should be described in the report as well as the section of the report where the descriptions should be located. Each input entry definition consists of: * "**Project**": Id of the project * "**Name**": name of the building block or simulation to describe * "**Type**": type of the building block/simulation (one of: "*Compound*", "*Event*", "*Formulation*", "*Individual*", "*ObserverSet*", "*Population*", "*Protocol*", "*Simulation*") * "**SectionReference**": Reference of the section where the input description will be inserted. Input description contains all input settings (model- type, calculation methods etc.) and all input parameters that deviate from the default incl. their value origins. #### Plots This section defines the type of plots (and some additional related information like tables and qualification measures) to generate for the report. ![](/files/-LsgfngyQhcbt2OgscgK) * "**PlotSettings**": OPTIONAL *Global* plot settings (pictures size, font properties). In addition, every plot can define its *local* plot settings. * If both (global and local) plot settings are defined for some plot: local settings will be used. * If neither global nor local plot settings are defined for some plot: program defaults will be used. * "**AxesSettings**": OPTIONAL *Global* axes settings **per plot type**. In addition, every plot can define its *local* axes settings. * If both (global and local) axes settings are defined for some plot: local settings will be used. * If neither global nor local axes settings are defined for some plot: program defaults will be used. * Global axes settings cannot be defined for "*AllPlots*" ```json "AxesSettings": { "ComparisonTimeProfile": [ { "Unit": "h", "Dimension": "Time", "Type": "X", "GridLines": false, "Scaling": "Linear" }, { "Unit": "ng/ml", "Dimension": "Concentration (mass)", "Type": "Y", "GridLines": false, "Scaling": "Log" } ], ``` * "**AllPlots**"; "**GOFMergedPlots**"; ... : different kinds of plots, explained in detail below. **AllPlots** All plots defined in the PK-Sim project *Project* under simulation *Simulation* will be placed into the report **using their settings defined in the PK-Sim project**. Thus one node from the "AllPlots"-section in the qualification plan will be expanded into N (N>=0) plots in the final report ```json "AllPlots": [ { "SectionReference": "sufentanil-ct-profiles", "Project": "Sufentanil-Pediatrics", "Simulation": "Guay 1991 patient 11" }, { "SectionReference": "sufentanil-ct-profiles", "Project": "Sufentanil-Pediatrics", "Simulation": "Guay 1991 patient 3" }, ``` NOTE: at the moment, only Time Profile Plots (Individual and Population) will be exported. **GOFMergedPlots** ``` "GOFMergedPlots": [ { "SectionReference": "gof-plots", "Title": "Midazolam concentration in plasma/blood", "PlotTypes": ["predictedVsObserved", "residualsOverTime"], "Artifacts": ["Plot", "Measure", "GMFE"], "Groups": [ { "Caption": "Midazolam iv", "Symbol": "Circle", "OutputMappings": [ { "Project": "Midazolam", "Simulation": "iv 0.001 mg (5 min)", "Output": "Organism|PeripheralVenousBlood|Midazolam|Plasma (Peripheral Venous Blood)", "ObservedData": "Hohmann 2015 - iv 0.001 mg - Plasma - agg. (n=16)", "Color": "#FF0000" }, ... ``` Two types of plots are supported here: * Predicted vs. Observed ![](/files/-Lsgfnh7Jaq3s14OAUaw) * Residuals over time ![](/files/-LsgfnhC2qLCvCL_8IZY) Combines data from several simulations; every simulation data can be displayed in different color/symbol. * "**Title**": title of the plot * "**SectionReference**": Reference of the section where the plot (and related artifacts; s. below) will be inserted. * "**PlotTypes**": Subset of {"*predictedVsObserved*", "*residualsOverTime*"} * "**Artifacts**": OPTIONAL must contain a subset of {"*Plot*", "*Measure*", "*GMFE*"}. Defines which artifacts will be generated in the report. If omitted: all artifacts will be generated * "*Plot*": Plot(s) as described above * "*Measure*": Table with the percentage of data points within X-Error fold | | Number | Ratio \[%] | | ---------------------- | ------ | ---------- | | Points total | 456 | - | | Points within 1.5-fold | 400 | 87,7 | | Points within 2-fold | 440 | 96,5 | * "*GMFE*": geometric mean fold error ![](/files/-LsgfnhLqp0szNT8fo8h) * "**Groups**": several simulations can be grouped All simulations from the same group have the same symbol in the plot * "**Caption**": group caption for the plot legend * "**Symbol**": one of "*Asterisk*", "*Circle*", "*Cross*", "*Diamond*", "*Point*", "*Square*", "*Triangle*" * "**OutputMappings**": definition of pairs {`Simulated output <=> Observed data set`} * "**Project**": Id of the project * "**Simulation**": name of the simulation * "**Output**": path of the simulated output curve of interest. This must be the path **internally used by PK-Sim** (without the leading simulation name) If you are not sure how such a path is defined: 1. Open project in PK-Sim 2. From the context menu of the simulation of interest: select "*Export simulation structure to file...*" 3. Open exported file with a text editor and look for "*OBSERVER*" 4. In the OBSERVER section: look for your output of interest and copy its path **without the leading simulation name**. E.g. in the example below correct output path for the qualification plan would be *Organism|PeripheralVenousBlood|Theophylline|Blood Cells* ``` --------------- OBSERVER (Non zero only) ---------- Observer: Blood Cells Path: S1_diss|Organism|PeripheralVenousBlood|Theophylline|Blood Cells ``` * "**ObservedData**": Id of an observed data set (s. [Observed data sets](#observed-data-sets) for details) * "**Color**": Color in "*#RRGGBB*" format. There are numerous free tools for color generation, e.g. **ComparisonTimeProfilePlots** Creates comparison time profile plots similar to [Comparison Charts in PK-Sim](https://docs.open-systems-pharmacology.org/working-with-pk-sim/pk-sim-documentation/pk-sim-simulations#comparison-chart-for-individual-or-population-simulations-in-one-plot). In addition, original results may be shifted in time. ``` "ComparisonTimeProfilePlots": [ { "SectionReference": "ct-profiles", "Title": "Ahonen 1995", "SimulationDuration": 20, "TimeUnit": "h", "OutputMappings": [ { "Project": "Itraconazole-Midazolam-DDI", "Simulation": "DDI Control - Midazolam - Ahonen 1995", "Output": "Organism|PeripheralVenousBlood|Midazolam|Plasma (Peripheral Venous Blood)", "ObservedData": "Ahonen 1995 - Midazolam - PO - 7.5 mg - Plasma - agg. (n=12)", "StartTime": 0, "TimeUnit": "h", "Color": "#2166ac", "Caption": "Control (without Itraconazole)", "Symbol": "Circle" }, ``` * "**Title**": title of the plot * "**SectionReference**": Reference of the section where the plot (and related artifacts; s. below) will be inserted. * "**SimulationDuration**" and "**TimeUnit**": s. below * "**OutputMappings**": definition of pairs {`Simulated output <=> Observed data set`} * "**Project**": Id of the project * "**Simulation**": name of the simulation * "**Output**": path of the simulated output curve of interest. This must be the path **internally used by PK-Sim** (without the leading simulation name) (s. [GOFMergedPlots](#gofmergedplots) for details!) * "**StartTime**" and "**TimeUnit**": Simulated and observed data will be shifted in the plot: * curves will be shifted along the time axis so that original "*StartTime*" corresponds to `Time=0` in the plot * only the time range \[`StartTime .. StartTime + SimulationDuration`] of the original data will be plotted * "**ObservedData**": Id of an observed data set (s. [Observed data sets](#observed-data-sets) for details) * "**Color**": Color in "*#RRGGBB*" format. (s. [GOFMergedPlots](#gofmergedplots) for details). Will be used for both simulated output and observed data * "**Symbol**": Symbol (s. [GOFMergedPlots](#gofmergedplots) for details) - will be used for observed data only ![](/files/-LsgfnhTyQEDyl2g7ujE) **DDIRatioPlots** Creates DDI Ratio plots as described e.g. in Hanke et. al (\[[106](/references/references#106)]) ![](/files/-LsgfnhWfHOhMlFqBC3I) Two types of plots are supported here: * Predicted vs. Observed (generates plots like in the example above) * Residuals vs. Observed (generates plots `Predicted/Observed vs. Observed`) ```json "DDIRatioPlots": [ { "SectionReference": "ddi-ratio-plots", "Title": "CYP3A4 DDI", "PKParameters": ["AUC", "CMAX"], "PlotTypes": ["predictedVsObserved", "residualsVsObserved"], "Artifacts": ["GMFE","Measure","Plot","Table"], "Subunits": ["Mechanism", "Perpetrator", "Victim"], "Groups": [ { "Caption": "Itra+Mida (Mida iv)", "Color": "#FF0000", "Symbol": "Square", "DDIRatios": [ { "Output": "Organism|PeripheralVenousBlood|Midazolam|Plasma (Peripheral Venous Blood)", "ObservedData": "DDI Ratios", "ObservedDataRecordId": 378, "SimulationControl": { "Project": "Itraconazole-Midazolam-DDI", "Simulation": "DDI Control - Midazolam - Olkkola 1996 (iv, day 4)", "StartTime": 0, "EndTime": 9999, "TimeUnit": "h" }, "SimulationDDI": { "Project": "Itraconazole-Midazolam-DDI", "Simulation": "DDI Treatment - Itraconazole/Midazolam - Olkkola 1996", "StartTime": 74, "EndTime": 122, "TimeUnit": "h" } } ] }, ``` * "**Title**": title of the plot * "**SectionReference**": Reference of the section where the plot (and related artifacts; s. below) will be inserted. * "**PKParameter**": PK Parameter for which DDI Ratios will be calculated. Subset of {"*AUC*", "*CMAX*"} * if both "*AUC*" and "*CMAX*" were selected: **2** plots will be generated (one for AUC Ratio and one for CMAX Ratio) * "**PlotTypes**": Subset of {"*predictedVsObserved*", "*residualsVsObserved*"} * if both "*predictedVsObserved*" and "*residualsVsObserved*" were selected: **both** plots will be generated for each selected PK-Parameter. Thus selecting this option in combination with \["AUC", "CMAX"] will result in generation of 4 plots in the report: * AUC Ratio predicted vs. observed * AUC Ratio residuals vs. observed * CMAX Ratio predicted vs. observed * CMAX Ratio residuals vs. observed * "**Artifacts**": OPTIONAL must contain a subset of {"*Plot*", "*Measure*", "*GMFE*", "*Table*"}. Defines which artifacts will be generated in the report. If omitted: all artifacts will be generated * "*Plot*": Plot(s) as described above * "*Measure*": Table with the percentage of data points within X-Error fold | - | Number | Ratio \[%] | | --------------------------------------------------------------------------- | ------ | ---------- | | Points total | 456 | - | | Points within [Guest et. al](http://dmd.aspetjournals.org/content/39/2/170) | 400 | 87,7 | | Points within 2-fold | 440 | 96,5 | * "*GMFE*": geometric mean fold error (s. [GOFMergedPlots](#gofmergedplots) for details) * "*Table*": creates a table containing quantitative values of all predicted and observed AUC,CMAX and corresponding DDI-Ratios and additional information about Control and DDI simulation (similar to the [table described in Hanke et. al](https://www.ncbi.nlm.nih.gov/pmc/articles/PMC6202474/table/psp412343-tbl-0001/)) * "**Subunits**": OPTIONAL Subset of {"*Mechanism*", "*Perpetrator*", "*Victim*"}. If defined, additional subchapters will be generated with DDI ratio plots grouped by the mechanism of action, perpetrator and victim. [Example report with subunits](https://github.com/Open-Systems-Pharmacology/OSP-Qualification-Reports/blob/v11.0/DDI_Qualification_CYP3A4/report.md) * "**Groups**": plotted DDI ratios can be grouped. Each group has its own caption, color and symbol * "**Caption**": plot caption * "**Color**": color in "*#RRGGBB*" format. (s. [GOFMergedPlots](#gofmergedplots) for details). * "**Symbol**": group symbol (s. [GOFMergedPlots](#gofmergedplots) for details) * "**DDIRatios**": list of DDI ratios belonging to the group. Each DDI Ratio is defined by: * "**Output**": path of the simulated output curve for which DDI ratio of interest will be calculated. This must be the path **internally used by PK-Sim** (without the leading simulation name) (s. [GOFMergedPlots](#gofmergedplots) for details!). * "**ObservedData**": Id of an observed data set (s. [Observed data sets](#observed-data-sets) for details) * "**ObservedDataRecordId**": Id of the data record (line) within the given observed data set. (corresponds to the **Id**-column of the data set) * "**SimulationControl**": description of the Control/Placebo simulation, given by: * "**Project**": Id of the project * "**Simulation**": name of the simulation * "**StartTime**", "**EndTime**" and "**TimeUnit**": PK-Parameter(s) of interest will be calculated in the time range \[`StartTime .. EndTime`]. * If the "**EndTime**" is set to "*Inf*": time range will be \[`StartTime .. Simulation End Time`] * "**SimulationDDI**": description of the DDI simulation, given in the same way as Control simulation **PKRatioPlots** Creates plots of predicted/observed ratios for PK parameters of interest ![](/files/-LsgfnhdxHNXZD6QeLPq) ``` "PKRatioPlots": [ { "Title": "Overall predictivity of the PBPK models. Open circles represent...", "SectionReference": "pk-ratio-plots", "PKParameters": ["AUC", "CL"], "Artifacts": ["GMFE", "Measure", "Plot", "Table"], "Groups": [ { "Caption": "Caption", "Color": "#000000", "Symbol": "Circle", "PKRatios": [ { "Project": "Sufentanil", "Simulation": "Davis 1987 15.5months", "Output": "Organism|ArterialBlood|Plasma|Sufentanil|Concentration in container", "ObservedData": "PK-Parameter", "ObservedDataRecordId": 5130 } ``` * "**Title**": title of the plot * "**SectionReference**": Reference of the section where the plot (and related artifacts; s. below) will be inserted. * "**PKParameter**s": PK Parameter for which PK Ratios will be calculated. Subset of {"*AUC*", "*CL*"} * if both "*AUC*" and "*CL*" were selected: **2** plots will be generated (one for AUC and one for Clearance) * "**Artifacts**": OPTIONAL must contain a subset of {"*Plot*", "*Measure*", "*GMFE*", "*Table*"}. Defines which artifacts will be generated in the report. If omitted: all artifacts will be generated * "*Plot*": Plot(s) as described above * "*Measure*": Table with the percentage of data points within X-Error fold (s. [GOFMergedPlots](#gofmergedplots) for details) * "*GMFE*": geometric mean fold error (s. [GOFMergedPlots](#gofmergedplots) for details) * "*Table*": creates a table containing quantitative values of all predicted and observed AUC and/or CL and corresponding PK-Ratios, e.g. | Study ID | Age \[y] | BodyWeight \[kg] | Predicted AUC \[µmol\*h/l] | Observed AUC \[µmol\*h/l] | Pred/Obs AUC Ratio | | ------------: | -------: | ---------------: | -------------------------: | ------------------------: | -----------------: | | Larson 2013 | 15 | 56 | 1.4103 | 15.7 | 1.4103 | | Larson 2013 | 9 | 29.4 | 0.85609 | 18 | 0.85609 | | Nachmann 2013 | 15.2 | 56.2267 | 1.0989 | 10.2 | 1.0989 | | Nachmann 2013 | 10 | 31.5 | 1.063 | 13.4 | 1.063 | | Rizk 2015 | 1.25 | 8.5 | 1.7188 | 19.8 | 1.7188 | * "**Groups**": plotted PK ratios can be grouped. Each group has its own caption, color and symbol * "**Caption**": plot caption * "**Color**": color in "*#RRGGBB*" format. (s. [GOFMergedPlots](#gofmergedplots) for details). * "**Symbol**": group symbol (s. [GOFMergedPlots](#gofmergedplots) for details) * "**PKRatios**": list of PK ratios belonging to the group. Each PK Ratio is defined by: * "**Project**": Id of the project * "**Simulation**": name of the simulation * "**Output**": path of the simulated output curve for which DDI ratio of interest will be calculated. This must be the path **internally used by PK-Sim** (without the leading simulation name) (s. [GOFMergedPlots](#gofmergedplots) for details!). * "**ObservedData**": Id of an observed data set (s. [Observed data sets](#observed-data-sets) for details) * "**ObservedDataRecordId**": Id of the data record (line) within the given observed data set. (corresponds to the **Id**-column of the data set) ### How generated artifacts are combined into a report All static and dynamic elements described in a qualification plan are compiled into a report in the following order: 1. Intro (if defined in the qualification plan) 2. Table of Contents (is generated automatically) 3. (Top level) sections **in order of their appearance in the qualification plan**. Per section: 3.1 Static content of the section 3.2 For all inputs **with SectionReference = Reference of the current section**: generated input descriptions **in order of appearance in the qualification plan** 3.3 For all plots **with SectionReference = Reference of the current section**: generated plots (and related artifacts) **in order of appearance in the qualification plan** 3.4 Subsections of the current section (if any) **in order of appearance in the qualification plan**. Per subsection ... (s. 3.1..3.4) ## Creating a (re-)qualification plan part II: Tools 1. Install VSCode (Visual Studio Code). * Download User-Installer or System-Installer from 2. If you are behind a firewall: configure firewall proxy * Start VSCode * Go to File►Preferences►Settings * Then go to User Settings►Application►Proxy * Enter your Firewall-Proxy 3. Install the snippets file * Download *Snippets for Visual Studio Code* (**qualification.code-snippets**) from * Copy this file to `C:\Users\\AppData\Roaming\Code\User\snippets` * In case you are using *portable* version of VSCode: copy the snippets file to `\data\user-data\User\snippets` (create the folder if it does not exist) * Restart VSCode 4. Create/Edit a qualification plan * Create a new empty file and **save it as .json** (unless the file was saved as json, snippets will not work) * For every element of a qualification plan (project, plot, section, input) there is a **predefined code snippet**, which will create a skeleton of this element. * To use a snippet, type its **shortcut** and press ENTER * The full list of qualification plan snippets is given in the table below. **Parent node** column describes at which places of a qualification plan a snippet can be used. * The first snippet to be used is always `bs`(*bootstrap*) - this will create a skeleton of a qualification plan * All other snippets are defined as abbreviations of "Add XYZ". * Full snippets list | Shortcut | Description | Parent node | | -------- | ---------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | bs | Creates the skeleton for a qualification plan | •ROOT | | ap | Add a project reference | •Projects | | abb | Adds a building block reference. Useful to replace a building block in a project | •Projects{i}/BuildingBlocks | | asp | Adds a simulation parameter reference. Useful to replace a parameter in a simulation with a parameter from another simulation | •Projects{i}/SimulationParameters | | aod | Adds an observed data reference. Only for external observed data sources | •ObservedDataSets | | ai | Adds an input (reference to a building block or simulation in a given project) | •Inputs | | aintro | Adds an introduction chapter | •Intro | | as | Adds a section |

•Sections
•Sections{i}/Sections …

| | aps | Adds the default plot settings configuration (global or local) |

==== GLOBAL ====
•Plots
==== LOCAL ====
•GOFMergedPlots{i}
•ComparisonTimeProfilePlots{i}
•DDIRatioPlots{i}
•PKRatioPlots{i}

| | aas | Adds the global axes settings skeleton | •Plots/AxesSettings | | axy | Adds axes X and Y settings content (global or local) |

==== GLOBAL ====
•Plots/AxesSettings/GOFMergedPlotsPredictedVsObserved
•Plots/AxesSettings/GOFMergedPlotsResidualsOverTime
•Plots/AxesSettings/ComparisonTimeProfile
•Plots/AxesSettings/DDIRatioPlotsPredictedVsObserved
•Plots/AxesSettings/DDIRatioPlotsResidualsVsObserved
•Plots/AxesSettings/PKRatioPlots
==== LOCAL ====
•Plots/GOFMergedPlots{i}/AxesPredictedVsObserved
•Plots/GOFMergedPlots{i}/AxesResidualsOverTime
•Plots/ComparisonTimeProfilePlots{i}/Axes
•Plots/DDIRatioPlots{i}/AxesPredictedVsObserved
•Plots/DDIRatioPlots{i}/AxesResidualsVsObserved
•Plots/PKRatioPlots{i}/Axes

| | aap | Adds an all plot entry for a simulation | •Plots/AllPlots | | agof | Adds a GOFMergedPlot entry | •Plots/GOFMergedPlots | | agofg | Adds a GOFMergedPlot group entry | •Plots/GOFMergedPlots{i}/Groups | | agofo | Adds a GOFMergedPlot OutputMapping entry (to be used within a group) | •Plots/GOFMergedPlots{i}/Groups{j}/OutputMappings | | actp | Adds a ComparisonTimeProfile entry | •Plots/ComparisonTimeProfilePlots | | actpo | Adds a ComparisonTimeProfile OutputMapping entry | •Plots/ComparisonTimeProfilePlots{i}/OutputMappings | | addir | Adds a DDIRatioPlot entry | •Plots/DDIRatioPlots | | addirg | Adds a DDIRatioPlot group entry | •Plots/DDIRatioPlots{i}/Groups | | addirr | Adds a DDIRatioPlot ratio entry (to be used within a group) | •Plots/DDIRatioPlots{i}/Groups{j}/DDIRatios | | apkr | Adds a PKRatioPlot entry | •Plots/PKRatioPlots | | apkrg | Adds a PKRatioPlot group entry | •Plots/PKRatioPlots{i}/Groups | | apkrr | Adds a PKRatioPlot ratio entry (to be used within a PKRatioPlot) | •Plots/PKRatioPlots{i}/Groups{j}/PKRatios | * If you do not remember the shortcut of a snippet: \_ either start typing: the list of all snippets starting with this shortcut will be shown via Intellisense \_ or press CTRL+SPACE: the list of ALL snippets will be shown. Then just navigate to the right snippet and select it ![](/files/-Lsgfnhr1qjBZ2Oszmcb) * After you inserted a skeleton via snippet: fill all the placeholders with correct information. Just start typing (don't click with the mouse!) into the first entry; once finished - press TAB to switch to the next input ![](/files/-LsgfnhwK4drxO-iQGG9) * If a value to be entered is an enumeration: click between double quotes and press CTRL+SPACE, then select from the list ![](/files/-LsgfnhzT4z58MPpoyNU) * If a Dimension/Unit pair has to be defined: select the dimension first (CTRL+SPACE), AFTER that select the unit ![](/files/-Lsgfni2WU6YjeQZg-vT) * Every time when a new element of a qualification plan was entered via snippet (or manually) and filled out: immediately check errors and warnings and correct them as soon as possible. ![](/files/-Lsgfni6MDxFPwInNNaR) * When adding a new element of NON-EMPTY array, do not forget a comma before or after inserted element. (Before when inserted as last element, after otherwise). 5. Some helpful links for editing json files with VSCode: * Getting started with VSCode: * Editing JSON with VSCode: * Extending/Modifying Snippets: ## Processing a (re-)qualification plan ### Tools Creation of a qualification report from a qualification plan requires installation of additional tools, which are not part of the OSP Suite setup. All required tools can be downloaded from * **QualificationRunner**: download `qualificationrunner-portable-setup_X.Y.Z.zip` and unzip it into any folder on your hard disc. * **Reporting Engine**. Follow the installation instructions under ### Creating a report in Markdown format A good starting point is . Download this repository locally and adjust `workflow.R` in the subfolder *Evaluation* (s. comments in the file). Execute `createQualificationReport(...)`. S. for further details. #### Converting Markdown report to pdf. Different (commercial and free) markdown to pdf converters are available. We recommend to use Typora () for this task. # ospsuite-R Documentation ### The ospsuite-R package The **ospsuite-R** package provides the functionality of loading, manipulating, and simulating the simulations created in the software tools PK-Sim and MoBi. The documentation of the package can be found here: ### Installing the ospsuite-R package Installation instructions are provided here: ### Articles Specific workflows and details regarding the ospsuite-R package can be found here: ### References The list of functions defined in the package can be found here: # Reporting Engine (RE) ### Reporting Engine The **Reporting Engine (RE)** package provides the functionality to create reports for the Open Systems Pharmacology models (e.g. *Qualification Reports*) The documentation of the package can be found here: ### Articles Specific workflows and details regarding the **RE** package can be found here: ### References The list of functions defined in the package can be found here: # TLF Library ### Tables, Listings and Figures Library (TLF) An implementation of the Table, Listing and Figure concepts in R. The **tlf** package is used by both the **Reporting Engine (RE)** R package and by the **ospsuite** R package. The documentation of the package can be found here: ### Articles Specific workflows and details regarding the **tlf** package can be found here: ### References The list of functions defined in the package can be found here: # Dimensions and Units ## A.1. Dimensions and Base Units Here you find an overview of all dimensions with their base units. Default display units are listed, where deviating from base units. **A.1. All dimensions and base units** | Dimension | Base unit | Deviating default display unit | | ------------------------------ | ------------------------- | ------------------------------ | | Abundance per mass protein | µmol/kg mic. protein | pmol/mg mic. protein | | Abundance per tissue | µmol/kg tissue | pmol/g tissue | | Age in years | year(s) | year(s) | | Age in weeks | week(s) | week(s) | | Amount | µmol | µmol | | Amount per time | µmol/min | µmol/min | | Area | dm² | cm² | | AUC (mass) | kg\*min/l | µg\*min/l | | AUC (molar) | µmol\*min/l | µmol\*min/l | | AUCM (molar) | µmol\*min²/l | µmol\*min²/l | | BMI | kg/dm² | kg/m² | | CL per mass protein | l/min/kg mic. protein | µl/min/mg mic. protein | | CL per recombinant enzyme | l/min/µmol rec. enzyme | µl/min/pmol rec. enzyme | | Concentration (mass) | kg/l | mg/l | | Concentration (molar) | µmol/l | µmol/l | | Inversed concentration (molar) | l/µmol | l/µmol | | Concentration (molar) per time | µmol/l/min | µmol/l/min | | Compliance | l/(kg/(dm\*min²)) | ml/mmHg | | Compliance (Area) | dm²/(kg/(dm\*min²)) | cm²/mmHg | | Count | x10^6 | x10^6 | | Count per mass | x10^6/kg | x10^6/g | | Count per volume | x10^6/l | x10^6/ml | | CV Viscosity | kg/(dm\*min) | s\*mmHg | | CV Viscosity per Volume | (kg/(dm\*min))/l | s\*mmHg/ml | | CV mmHg\*s²/ml | (kg/dm)/l | mmHg\*s²/ml | | Density | kg/dm³ | g/cm³ | | Diffusion coefficient | dm²/min | cm²/min | | Dose per body weight | kg/kg | mg/kg | | Dose per body surface area | kg/dm² | mg/m² | | Elastance | (kg/(dm\*min²))/l | mmHg/ml | | Energy | kg\*dm²/min² | kcal | | Flow | l/min | l/min | | Flow per weight organ | l/min/kg organ | ml/min/100g organ | | Flow per weight | l/min/kg | ml/min/kg | | Flow per body surface area | l/min/dm² | ml/min/1.73m² | | Flow² | (l/min)² | (l/min)² | | Fraction | | | | Hydraulic conductivity | l/min/(kg\*dm/min²) | ml/min/N | | Inversed length | 1/dm | 1/cm | | Inversed mol | 1/µmol | 1/mol | | Inversed time | 1/min | 1/min | | Inversed volume | 1/l | 1/l | | Length | dm | cm | | Log Units | Log Units | Log Units | | Mass | kg | kg | | Mass per area | kg/dm² | µg/cm² | | Mass per time | kg/min | kg/min | | Mass per area per time | kg/dm²/min | µg/cm²/h | | Mass per tissue | kg/kg | mg/g | | Molecular weight | kg/µmol | g/mol | | Pressure | kg/(dm\*min²) | mmHg | | Resistance | kg/(dm\*min²)\*min/l | mmHg\*s/ml | | Resolution | pts/min | pts/h | | RT | (kg\*dm/min²)\*dm/µmol | N\*cm/mol | | Second order rate constant | l/µmol/min | l/µmol/min | | Slope | l/(kg/(dm\*min²))/dm² | ml/mmHg/m² | | Time | min | h | | Time² | min² | s² | | Velocity | dm/min | cm/min | | Viscosity | min/l | s/ml | | Vmax per mass protein | µmol/min/kg mic. protein | pmol/min/mg mic. protein | | Vmax per weight organ tissue | µmol/min/kg tissue | µmol/min/kg tissue | | Vmax per recombinant enzyme | µmol/min/µmol rec. enzyme | nmol/min/pmol rec. enzyme | | Vmax per transporter | µmol/min/µmol transporter | nmol/min/pmol transporter | | Volume | l | l | | Volume per body weight | l/kg | ml/kg | | Ampere | A | A | | Becquerel | 1/min | Bq | | Candela | cd | cd | | Coulomb | A\*min | C | | Farad | F | F | | Gray | Gy | Gy | | Henry | H | H | | Hertz | 1/min | Hz | | Joule | J | J | | Katal | µmol/min | kat | | Temperature | K | °C | | Kelvin | K | K | | Lumen | lm | cd\*sr | | Lux | lx | lx | | Newton | (kg\*dm)/min² | N | | Ohm | Ohm | Ohm | | Radian | rad | rad | | Siemens | S | S | | Sievert | Sv | Sv | | Steradian | sr | sr | | Tesla | T | T | | Volt | V | V | | Watt | W | W | | Weber | Wb | Wb | # OSP Suite Fact Sheet ## Main modeling and simulation features: * PBPK modeling of small molecules and biologics * Species Extrapolation / First in Human dose prediction * Parent-Metabolite Studies / Drug-Drug-Interaction * Pediatric Study Design – PIP/PDP support * Special Populations: Hepatic/Renal impairment / Obese / Elderly / (pre-) term neonates / Children / Pregnant women / more * Formulations / Meal effects * PBPK/PD, QSP as well as pathway, network and disease modeling * Modular model building approach, enabling collaboration, re-usability, and validation of developed modules ## Model building blocks ### Organisms * Pre-parameterized whole-body PBPK models including detailed integrated GI tract for * Human * Monkey * Dog (beagle and mongrale) * Minipig * Rat * Mouse * Rabbit * Allowing for full flexibility for parameterization of (anthropo)metrics, anatomical and physiological properties, protein expression levels, etc. * Most important organs included. For each organ optional processes can be added: * Metabolizing pathways * Different active transporter types(influx, efflux, bi-directional) * Protein binding partners * Biliary tract included, enables enterohepatic cycling * Scaling of Individuals Scaling can be used to change the biometrics of an existing individual, i.e. an adult model may be scaled to an infant model while maintaining/scaling all specific modifications ### Populations * Database for population simulations with distributions of anatomical and physiological parameters for * East Asian (Tanaka, 1996) \[[74](/references/references#74)] * Black American (NHANES, 1997) \[[82](/references/references#82)] * European (ICRP, 2002) \[[84](/references/references#84)], \[[113](/references/references#113)] * Mexican American -White (NHANES, 1997) \[[82](/references/references#82)] * White American (NHANES, 1997) \[[82](/references/references#82)] * Japanese \[[67](/references/references#67)] * Preterm \[[111](/references/references#111)] * Pregnant (Dallmann et al. 2017) \[[107 - 110](/references/references#107)] ### Protein Expression The PK-Sim® library includes large-scale gene-expression data from publicly available sources which were downloaded, processed, stored and customized such that they can be directly utilized in PBPK model building. Public database which were imported are * Whole genome expression arrays from ArrayExpress (European Informatics Institute, 2010, ) * RT-PCR derived gene expression (Nishimura et al., 2003; Nishimura and Naito, 2005, 2006) * Expressed sequence tags (EST) from UniGene (National Center for Biotechnology Information, 2010, ). ### Compounds * Full ADME characterization of drugs including * Molecular weight * Lipophilicity * Protein binding * Acid/base pKa * Solubility * Intestinal permeability * Specific protein binding kinetics * Enzyme specific metabolization kinetics * Transporter specific transport kinetics * Inhibition and induction parameters * and for large therapeutic molecules (e.g. antibodies) * Solute radius (calculated for molecular weight as per default) * Dissociation constant for binding to FcRn * Including a set of pre-parameterized standard compounds #### Partition Coefficients Prediction models for tissue partition coefficients * PK-Sim 2003 * Rodgers & Rowland * Schmitt * Poulin & Theil * Berezhkovsky #### Permeability Prediction models for cellular permeabilities and intestinal permeability ### Formulations * Dissolved * Particle distribution * Weibull * Lint80 * Table * 1st order * Zero order ### Administration protocols * Administration routes: * IV (Bolus and Infusion) * Oral * User defined (free choice of target organ/compartment) * Administration Schemes: * Single * once daily, bi-daily, … * complex (multi-)periodic schemes ![](/files/-LNl8UNGjV2zjceAw_-x) ### Events * Meals * Gallbladder emptying ### Observers ## Modeling tools ### Parameter identification (PI) A fully integrated PI Toolbox provides a straightforward means to adjust key model parameters automatically within user-defined ranges. It is possible to optimize multiple simulations, for example with different dose levels, and multiple observed data sets, simultaneously. A clear visualization of the optimization process and of the optimization results gives you full control and direct feedback whether the identification process was successful. ![](/files/-LNl8bKIJecCBqXQ2AWH) ![](/files/-LNl8bKLIQUskq1XfVRH) ![](/files/-LNl8bKpUz3TYylQXb9d) ![](/files/-LOWPzb2874-spDp6thU) * Simultaneous optimization of multiple simulations * Simultaneous optimization of multiple observed data sets * LLOQ (Lower Limit of Quantification) values are taken into account * Linking of multiple simulation parameters to one identification parameter (as absolute value or as a factor) * Lin/Log scaling of identification parameters * Lin/Log scaling of residuals * Multiple optimizations with randomized start values * Combining parameter identification with optimization for best suited partition coefficients/permeability methods * Available optimization algorithms: * Nelder-Mead * Levenberg-Marquardt * Monte-Carlo * Visual feedback during optimization * Time profile * Predicted vs. Observed * Error history: Total error vs number of evaluations * Total error: current/best value * Identification parameters: current/best value * Export of parameters history to MS-Excel * Visualization of optimization results * Time profile * Predicted vs. Observed * Residuals vs. Time * Histogram of Residuals * Total error * Number of evaluations * Identification parameters: min/max/start/best value * Warning if best values are "close to" boundaries * Easy cloning of PI configuration within a project * Replacing simulations in PI configuration without losing the settings * Update simulations with optimized parameter values * Calculation of time profile confidence intervals * **Confidence Interval**: Corresponds to the model error, which is based on the uncertainty of estimated parameters. This uncertainty is based on an estimation of the difference between the mean value of used observed data compared with the mean value of the (unknown) total data. ![](/files/-LNl8bLJgYZwSNHSWtgD) * **Visual Predictive Check Interval**: Corresponds to the uncertainty based on the data error. The data error is the standard deviation of the distribution of the used observed data. ![](/files/-LNl8bLMurmm0RwPcBo3) * **Prediction Interval**: Corresponds to the combination of the model error and the data error. It shows how much future measured data are expected to differ from the model predictions. ![](/files/-LNl8bLOoKjWqFh4ElFu) ### Sensitivity Analysis #### Sensitivity of PK-Parameters (AUC, CMax, …) vs. simulation parameters. Because PBPK models can be complex and contain numerous input parameters, it would be useful to know which input parameters have the most impact on the output curves. The Sensitivity Analysis tool provides an answer to this question. For a chosen simulation, the relative impact of selected - or all - input parameters on the PK parameters of the output curves is calculated and displayed. In addition, the input parameters can be ranked by their impact on a certain PK parameter of an output. Results of Sensitivity Analysis can be shown as: * Sensitivity table: ![](/files/-LNl8QczprrsKbyr2cIZ) * Ranking of most sensitive simulation parameters. Most sensitive parameters comprise all parameters that contribute to 90% of total sensitivity. ![](/files/-LNl8QcrJ9xVjchcyQCz) ### Lab Journal ("Working Journal") * Automated documentation of modeling work in model history working journal documenting including labeling and commenting function * Built-in working journal for manual annotation of models and simulations * Roll-back / undo functionality ![](/files/-LofNZRoicGSiLEpk1Ay) ![](/files/-LofNZRs-2svX4iu8IKC) ### Model Editor Full transparency and full edit access to all structural model properties ## Simulation Tools * Simulation creation by simple combining of previously defined building blocks * Simulation of individuals and populations If a human individual or population is selected the growth of the human individual(s) during the simulation time will be taken into account when choosing this option. Based on the human growth and maturation functions available for most parameters in PK-Sim® (e.g. organ volumes, blood flow rates, organ composition, etc.) the parameters are updated along the time scale of the simulation. This is important for multiple drug administration to e.g. preterm and term neonates, for which the rapid changes in anatomical and physiological properties can influence the pharmacokinetics during the simulated study circle. * Calculation of drug time courses in the most important organs for every subcompartment (Plasma, Endosome, Interstitial, Intracellular, Blood Cells) * Calculation of the fraction of dose metabolized/excreted * Plotting of all calculated time courses * Plot settings (axes, styles, etc.) * Individual simulations: * Time profile plots ![](/files/-LOWQ59oZsHVTWH-gQw3) * Population simulations * Time profile plots ![](/files/-LNl8SFbzxuD_Gb1fhqZ) ![](/files/-LNl8SFjbACa8CCxe1ie) \* Box-Whisker plots ![](/files/-LofNZRyTavMNTDo39je) \* Range plots ![](/files/-LofNZS00wHuCJhTr7vT) \* Scatter plots ![](/files/-LofNZS238Tcc_lpaGsR) * Multiple plots per simulation * Export of plotted/simulated results to Excel/CSV/Image * Calculation of the most important PK-Parameters * In all simulations * AUC\_tEnd * AUC\_inf * %AUC(tlast-inf) * AUC\_tEnd\_norm * AUC\_inf\_norm * AUC Ratio (AUCR) * C\_max * C\_max\_norm * C\_max Ratio (Cmax\_R) * C\_tEnd * t\_max * Half-Life * MRT * In simulations with intravenous administration * VSS(plasma) * Vd(plasma) * Vss(phys-chem) * Total plasma clearance CL * Total body clearance * In simulations with oral administration * Vss(plasma)/F * Vd(plasma)/F * Total plasma clearance/F * Fraction absorbed * Bioavailability * In simulations with multiple administrations * AUC\_inf\_tD1 * AUC\_inf\_tD1\_n * ...tDi-tDj * ...tDlast-tDEnd * ...tDlast-1- tDlast * C\_trough\_dDi * C\_trough\_dlast * In simulations with drug drug interactions * AUC Ratio * C\_max Ratio * Comparisons of calculated simulation results over multiple simulations (both individual and population simulations) * Cloning of simulations * Replacing of Building Blocks in already created simulations * Synchronization between a building block used to create a simulation and the simulation * Comparison between simulations * Comparison between building blocks and simulations ![](/files/-LofNZS675vdBFCamTH2) * Comparison of building blocks can also be done between two simulations on the same kind of building block ![](/files/-LofNZS809K9eb3ICzJ2) ## Data * Import of experimental (observed) data from: * MS Excel * CSV * Nonmem * Import of SBML models ## MoBi * Editing * Editing of PK-Sim simulations to the detail of all parameters, structural elements, transports, reactions, events, and more. * Adding features to PK-Sim models, like tumors, complex molecular interactions, or non-standard drug applications * Display and editing of a simulation as tree or diagram * Comparing: * Result comparison charts * Simulation and building block comparison, exportable list of differences * Merging of building blocks from different simulations * Parameter identification and sensitivity analysis * Re-sending simulations back to PK-Sim for population simulation * Documentation: * Integrated working journal, sharable with PK-Sim, for documentation * Automatic tracking of changes made in a history log file * Export * Export of simulated results as Excel file * Various formats of model exports and listings, like XML, Excel * Import * Import of model parameters from Excel files * Import of model files in SBML format for QSP model building * Building models from scratch, like reaction pathways into a user-built spatial structure or for compartmental modeling * Option to select frequently accessed parameters as favorites # References ### References & Information #### 1 A. C. Andersen. *The beagle as an experimental dog*. Iowa State University Press. University of Michigan. 616 pages. 1970. #### 2 [N. Balakrishnan (Editor). *Methods and Applications of Statistics in Clinical Trials, Volume 2: Planning, Analysis, and Inferential Methods*. John Wiley and Sons. 2014.](https://www.wiley.com/en-us/Methods+and+Applications+of+Statistics+in+Clinical+Trials,+Volume+2%3A+Planning,+Analysis,+and+Inferential+Methods-p-9781118304761) #### 3 [L. Baxter, H. Zhu, D. Mackensen, and R. Jain. *Physiologically based pharmacokinetic model for specific and nonspecific monoclonal antibodies and fragments in normal tissues and human tumor xenografts in nude mice*. Cancer Research. 54. 1517-28. 1994.](https://pubmed.ncbi.nlm.nih.gov/8137258) #### 4 [L.Z. Benet. *Basic Principles and Its Use as a Tool in Drug Metabolism*. in: Drug Metabolism and Drug Toxicity. J.R. Mitchell. M.G. Horning. Raven Press. New York, USA. pp. 199. 1984.](https://doi.org/10.1002/em.2860070617) #### 5 [L.M. Berezhkovskiy. *Volume of distribution at steady state for a linear pharmacokinetic system with peripheral elimination*. Journal of Pharmaceutical Sciences. 93(6). 1628-40. 2004.](https://pubmed.ncbi.nlm.nih.gov/15124219) #### 6 [A. C. Hindmarsh, P. N. Brown, K. E. Grant, S. L. Lee, R. Serban, D. E. Shumaker, and C. S. Woodward. *SUNDIALS: Suite of Nonlinear and Differential/Algebraic Equation Solvers*. ACM Transactions on Mathematical Software, 31(3), pp. 363-396, 2005.](https://computing.llnl.gov/sites/default/files/toms_sundials.pdf) #### 7 [P. Costa and J. M. Sousa Lobo. *Modeling and comparison of dissolution profiles*. Eur J Pharm Sci. 13(2). 123-33. 2001.](https://pubmed.ncbi.nlm.nih.gov/11297896) #### 8 C. Crone and D.G. Levitt. *Capillary permeability to small solutes*. in Handbook of Physiology: The Cardiovascular System: Microcirculation. E.M. Renkin. C.C. Michel. American Physiological Society. Bethesda, MD, USA. pp. 411–466. 1984. #### 9 [C. Dordas and P. H. Brown. *Permeability of Boric Acids across Lipid Bilayers and Factors Affecting it*. Journal of Membrane Biology. 175. 95-105. 2000.](https://pubmed.ncbi.nlm.nih.gov/10811971) #### 10 [J.B. Dressman, K. Thelen, and E. Jantratid. *Towards Quantitative Prediction of Oral Drug Absorption*. Clinical Pharmacokinetics. 47(10). 655-67. 2008.](https://pubmed.ncbi.nlm.nih.gov/18783296) #### 11 [A. N. Edginton, S. Willmann, B. Voith, and W. Schmitt. *A mechanistic approach to the scaling of clearance in children*. Clinical Pharmacokinetics. 45. 683-704. 2006.](https://pubmed.ncbi.nlm.nih.gov/16802850) #### 12 [A. N. Edginton, W. Schmitt, and S. Willmann. *Application of physiology-based pharmacokinetic and pharmacodynamic modeling* towards individualized propofol target controlled infusion. Advances in Therapy. 23. 143-158. 2006.](https://pubmed.ncbi.nlm.nih.gov/16644615/) #### 13 [A. N. Edginton, W. Schmitt, and S. Willmann. *Development and evaluation of a generic physiologically based pharmacokinetic model for children*. Clinical Pharmacokinetics. 45. 1013-1034. 2006.](https://pubmed.ncbi.nlm.nih.gov/16984214) #### 14 [A. N. Edginton, F.P. Theil, W. Schmitt, and S. Willmann. *Whole body physiologically-based pharmacokinetic models: their use in clinical drug development*. Expert Opinion on Drug Metabolism & Toxicology. 4(9). 1143-52. 2008.](https://pubmed.ncbi.nlm.nih.gov/18721109) #### 15 [A.N. Edginton, G. Ahr, S. Willmann, and H. Stass. *Defining the Role of Macrophages in Local Moxifloxacin Tissue Concentrations using Biopsy Data and Whole-Body Physiologically Based Pharmacokinetic Modelling*. Clinical Pharmacokinetics. 48(3). 181-7. 2009.](https://pubmed.ncbi.nlm.nih.gov/19385711) #### 16 [A. N. Edginton and G. Joshi. *Have physiologically-based pharmacokinetic models delivered?*. Expert Opin Drug Metab Toxicol. 929-34. 7(8). 2011.](https://pubmed.ncbi.nlm.nih.gov/21762039) #### 17 [A. N. Edginton and S. Willmann. *Physiology-based simulations of a pathological condition : prediction of pharmacokinetics in patients with liver cirrhosis*. Clinical Pharmacokinetics. 47(11). 743-52. 2008.](https://pubmed.ncbi.nlm.nih.gov/18840029) #### 18 [T. Eissing, L. Kuepfer, C. Becker, M. Block, K. Coboeken, T. Gaub, L. Goerlitz, J. Jaeger, R. Loosen, B. Ludewig, M. Meyer, C. Niederalt, M. Sevestre, H. U. Siegmund, J. Solodenko, K. Thelen, U. Telle, W. Weiss, T. Wendl, S. Willmann, and J. Lippert. *A computational systems biology software platform for multiscale modeling and simulation: integrating whole-body physiology, disease biology, and molecular reaction networks*. Front Physiol. 4. 2. 2011.](https://pubmed.ncbi.nlm.nih.gov/21483730) #### 19 [T. Eissing, J. Lippert, and S. Willmann. *Pharmacogenomics of Codeine, Morphine, and Morphine-6-Glucuronide: Model-Based Analysis of the Influence of CYP2D6 Activity, UGT2B7 Activity, Renal Impairment, and CYP3A4 Inhibition*. Mol Diagn Ther. 43-53. 16(1). 2012.](https://pubmed.ncbi.nlm.nih.gov/22352453) #### 20 [C.T. Ekstrom (Editor). *Introduction to Statistical Data Analysis for the Life Sciences, Second Edition*. CRC Press. 2014.](https://doi.org/10.1201/b17625) #### 21 [B. I. Escher and R. P. Schwarzenbach. *Partitioning of Substituted Phenols in Liposome-Water, Biomembrane-Water, and Octanol-Water Systems*. Environmental Science and Technology. 30. 260-270. 1996.](https://doi.org/10.1021/es9503084) #### 22 [P. Espie, D. Tytgat, M. L. Sargentini-Maier, I. Poggesi, and J. B. Watelet. *Physiologically based pharmacokinetics (PBPK)*. Drug Metab Rev. 41. 391-407. 2009.](https://pubmed.ncbi.nlm.nih.gov/19601719) #### 23 [L. Fahrmeir, T. Kneib, and S. Lang. *Regression Modelle, Methoden und Anwendungen*. Springer Verlag. 2009.](https://www.springer.com/de/book/9783642018367) #### 24 [F. Frezard and A. Garnier-Suillerot. *Permeability of Lipid Bilayer to Anthracycline Derivates. Role of the Bylayer Composition and of the Temperature*. Biochimica et Biophysica Acta. 1389. 13-22. 1998.](https://pubmed.ncbi.nlm.nih.gov/9443599) #### 25 [E. Galia, E. Nicolaides, D. Härter, R. Läbenberg, C. Reppas, and J. B. Dressman. *Evaluation of various dissolution media for predicting in vivo performance of class I and II drugs*. Pharmaceutical Research. 15. 698-705. 1998.](https://pubmed.ncbi.nlm.nih.gov/9619777) #### 26 [A. Garg and J. Balthasar. *Physiologically-based pharmacokinetic (PBPK) model to predict IgG tissue kinetics in wild-type and FcRn-knockout mice*. Journal of Pharmacokinetics and Pharmacodynamics. 34. 687-709. 2007.](https://pubmed.ncbi.nlm.nih.gov/17636457) #### 27 \[Henri P. Gavin. *The Levenberg-Marquardt method for nonlinear least squares curve-fitting problems*. 2016.]\( ) #### 28 [X. Ge, S. Yamamoto, S. Tsutsumi, Y. Midorikawa, S. Ihara, S. M. Wang, and H. Aburatani. *Interpreting expression profiles of cancers by genome- wide survey of breadth of expression in normal tissues*. Genomics.. 86(2). 127-41. 2005.](https://pubmed.ncbi.nlm.nih.gov/15950434/) #### 29 [R. Gebhardt. *Metabolic zonation of the liver: Regulation and implications for liver function*. Pharmacol. Ther.. 53(3). 275-354. 1992.](https://pubmed.ncbi.nlm.nih.gov/1409850) #### 30 [J. A. Goldsmith, N. Randall, and S. D. Ross. *On methods of expressing dissolution rate data.*. J Pharm Pharmacol. 30(6). 347-9. 1978.](https://pubmed.ncbi.nlm.nih.gov/26763) #### 31 [H. W. Haagard. *The Absorption, Distribution and Elimination of Ethyl Ether*. The Journal of Biological Chemistry. 59. 753-770. 1924.](https://www.sciencedirect.com/science/article/pii/S0021925818852589) #### 32 [M. W. Härter, J. Keldenich, and W. Schmitt. in Handbook of Combinatorial Chemistry. Vol. 2. K. C. Nicholaou. R. Hanko. W. Hartwig. Wiley-VCH. Weinheim, Germany. 2002.](https://onlinelibrary.wiley.com/doi/10.1002/3527603034.ch26) #### 33 [W. L. Hayton. *Maturation and Growth of Renal Function: Dosing Renally Cleared Drugs in Children*. AAPS PharmSci. 2(1). E3. 2002.](https://pubmed.ncbi.nlm.nih.gov/11741219) #### 34 [P. Holliger and P. J. Hudson. *Engineered antibody fragments and the rise of single domains*. Nat Biotechnol.. 23(9). 1126-36. 2005.](https://pubmed.ncbi.nlm.nih.gov/16151406) #### 35 [H. G. Holzhutter, D. Drasdo, T. Preusser, J. Lippert, and A. M. Henney. *The virtual liver: a multidisciplinary, multilevel challenge for systems biology*. Wiley Interdiscip Rev Syst Biol Med. 2012.](https://pubmed.ncbi.nlm.nih.gov/22246674) #### 36 [R. Kawei, M. Lemaire, J. L. Steimer, A. Bruelisauer, W. Niederberger, and M. Rowland. *Physiology Based Pharmacokinetic Study on a Cyclosporin Derivate, SDZ IMM 125*. Journal of Pharmacokinetics and Biopharmaceutics. 22. 327-365. 1994.](https://pubmed.ncbi.nlm.nih.gov/7791036) #### 37 [G. Kersting, S. Willmann, G. Wurthwein, J. Lippert, J. Boos, and G. Hempel. *Physiologically based pharmacokinetic modelling of high- and low-dose etoposide: from adults to children*. Cancer Chemother Pharmacol. 397-405. 69(2). 2012.](https://pubmed.ncbi.nlm.nih.gov/21789689) #### 38 [B. Krippendorf, R. Neuhaus, and P. Lienau. *Mechanism-Based Inhibition: Deriving KI and kinact Directly from Time-Dependent IC50 Values*. J. of Biomolecular Screening. 14((8). 2009.](https://pubmed.ncbi.nlm.nih.gov/19675314) #### 39 [L. Kuepfer, J. Lippert, and T. Eissing. *Multiscale mechanistic modeling in pharmaceutical research and development*. Adv Exp Med Biol. 543-61. 736. 2012.](https://pubmed.ncbi.nlm.nih.gov/22161351) #### 40 [F. Langenbucher. *Linearization of dissolution rate curves by the Weibull distribution*. J Pharm Pharmacol.. 24(12). 979-81. 1972.](https://pubmed.ncbi.nlm.nih.gov/4146531) #### 41 [D. G. Levitt. *Physiologically based pharmacokinetic modeling of arterial- antecubital vein concentration difference*. BMC Clinical Pharmacology. 4. 2. 2004.](https://pubmed.ncbi.nlm.nih.gov/15053829) #### 42 [E. D. Lobo, R. J. Hansen, and J. P. Balthasar. *Antibody Pharmacokinetics and Pharmacodynamics*. J. Pharm. Sci.. 93(11). 2645-2668. 2004.](https://pubmed.ncbi.nlm.nih.gov/15389672) #### 43 [A. Loidl-Stahlhofen, T. Hartmann, M. Schöttner, C. Röhring, H. Brodowsky, J. Schmitt, and J. Keldenich. *Multilamellar Liposomes and Solid- Supported Lipid Membranes (TRANSIL): Screening of Lipid-Water Partitioning Toward a High-Throughput Scale*. Pharmaceutical Research. 18. 1782-1788. 2001.](https://pubmed.ncbi.nlm.nih.gov/11785701) #### 44 [G. Loizou, M. Spendiff, H.A. Barton, J. Bessems, F.Y. Bois, M.B. d'Yvoire, H. Buist, H.J. Clewell 3rd, B. Meek, U. Gundert-Remy, G. Goerlitz, and W. Schmitt. *Development of good modelling practice for physiologically based pharmacokinetic models for use in risk assessment: the first steps*. Regulatory Toxicology and Pharmacology. 50(3). 400-11. 2008.](https://pubmed.ncbi.nlm.nih.gov/18331772) #### 45 [K. Madsen, H.B. Nielsen, and O. Tingleff. *METHODS FOR NON- LINEAR LEAST SQUARES PROBLEMS*. 2nd Edition, April 2004.](http://www2.imm.dtu.dk/pubdb/views/edoc_download.php/3215/pdf/imm3215.pdf) #### 46 [M. Meyer, S. Schneckener, B. Ludewig, L. Kuepfer, and J. Lippert. *Using expression data for quantification of active processes in physiologically- based pharmacokinetic modeling*. Drug Metab Dispos. 2012.](https://pubmed.ncbi.nlm.nih.gov/22293118) #### 47 [John A. Nelder and R. Mead. *A simplex method for function minimization*. Computer Journal. 7. 308-313. 1965.](https://doi.org/10.1093/comjnl/7.4.308) #### 48 [I. Nestorov. *Whole-body physiologically based pharmacokinetic models*. Exp Opin Drug Metab Toxicol. 3. 235-249. 2007.](https://pubmed.ncbi.nlm.nih.gov/17428153) #### 49 [M. Nishimura, H. Yaguti, H. Yoshitsugu, S. Naito, and T. Satoh. *Tissue distribution of mRNA expression of human cytochrome P450 isoforms assessed by high-sensitivity real-time reverse transcription PCR*. Yakugaku Zasshi.. 123(5). 369-75. 2003.](https://pubmed.ncbi.nlm.nih.gov/12772594) #### 50 [M. Nishimura and S. Naito. *Tissue-specific mRNA expression profiles of human ATP-binding cassette and solute carrier transporter superfamilies*. Drug Metab Pharmacokinet. 20(6). 452-77. 2005.](https://pubmed.ncbi.nlm.nih.gov/16415531) #### 51 [M. Nishimura and S. Naito. *Tissue-specific mRNA expression profiles of human phase I metabolizing enzymes except for cytochrome P450 and phase II metabolizing enzymes*. Drug Metab Pharmacokinet. 21(5). 357-74. 2006.](https://pubmed.ncbi.nlm.nih.gov/17072089) #### 52 [P. Poulin, K. Schoenlein, and F.P. Theil. *Prediction of adipose tissue: plasma partition coefficients for structurally unrelated drugs*. Journal of Pharmaceutical Sciences. 90(4). 436-47. 2001.](https://pubmed.ncbi.nlm.nih.gov/11170034) #### 53 [P. Poulin and F. P. Theil. *A Priori Prediction of Tissue: Plasma Partition Coefficients of Drugs to Facilitate the Use of Physiologically-Based Pharmacokinetic Models in Drug Discovery*. Journal of Pharmaceutical Sciences. 89. 16-35. 2000.](https://pubmed.ncbi.nlm.nih.gov/10664535) #### 54 [P. Poulin and F.P. Theil. *Prediction of pharmacokinetics prior to in vivo studies. 1. Mechanism-based prediction of volume of distribution*. Journal of Pharmaceutical Sciences. 91(1). 129-56. 2002.](https://pubmed.ncbi.nlm.nih.gov/11782904) #### 55 [P. Poulin and F.P. Theil. *Prediction of pharmacokinetics prior to in vivo studies. II. Generic physiologically based pharmacokinetic models of drug disposition*. Journal of Pharmaceutical Sciences. 91(5). 1358-70. 2002.](https://pubmed.ncbi.nlm.nih.gov/11977112) #### 56 [NJ. Proctor, GT. Tucker, and A. Rostami-Hodjegan. *Predicting drug clearance from recombinantly expressed CYPs: intersystem extrapolation factors.*. Xenobiotica. 34(2). 151-78. 2004.](https://pubmed.ncbi.nlm.nih.gov/14985145) #### 57 [B. Rippe and B. Haraldsson. *Fluid and protein fluxes across small and large pores in the microvasculature. Application of two-pore equations*. Acta Physiol Scand.. 131(3). pp 411-28. 1987.](https://pubmed.ncbi.nlm.nih.gov/3321914) #### 58 [B. Rippe and B. Haraldsson. *Transport of macromolecules across microvascular walls: the two-pore theory*. Am Physiological Soc.. 74. pp 163-219. 1994.](https://pubmed.ncbi.nlm.nih.gov/8295933) #### 59 [T. Rodgers, D. Leahy, and M. Rowland. *Physiologically Based Pharmacokinetic Modeling 1: Predicting the Tissue Distribution of Moderate-to-Strong Bases*. Journal of Pharmaceutical Sciences. 94. 1259-1275. 2005.](https://pubmed.ncbi.nlm.nih.gov/15858854) #### 60 [T. Rodgers, D. Leahy, and M. Rowland. *Tissue Distribution of Basic Drugs: Accounting for Enantiomeric, Compound and Regional Differences Amongst beta-Blocking Drugs in Rat*. Journal of Pharmaceutical Sciences. 94. 1237-1248. 2005.](https://pubmed.ncbi.nlm.nih.gov/15858851) #### 61 [T. Rodgers and M. Rowland. *Physiologically Based Pharmacokinetic Modeling 2: Predicting the Tissue Distribution of Acids, Very Weak Bases, Neutrals and Zwitterions*. Journal of Pharmaceutical Sciences. 95. 1238-1257. 2006.](https://pubmed.ncbi.nlm.nih.gov/16639716) #### 62 [T. Rodgers and M. Rowland. *Mechanistic Approaches to Volume of Distrubtion Predictions: Understanding the Processes*. Pharmaceutical Research. 24. 918-933. 2007.](https://pubmed.ncbi.nlm.nih.gov/17372687) #### 63 [AD. Rodrigues. *Integrated cytochrome P450 reaction phenotyping: attempting to bridge the gap between cDNA-expressed cytochromes P450 and native human liver microsomes*. Biochem Pharmacol. 465-80. 57 (5). 1999.](https://pubmed.ncbi.nlm.nih.gov/9952310) #### 64 [A. Rostami-Hodjegan and GT. Tucker. *Simulation and prediction of in vivo drug metabolism in human populations from in vitro data.*. Nat Rev Drug Discov. 6(2). 140-8. 2007.](https://pubmed.ncbi.nlm.nih.gov/17268485) #### 65 M. Rowland and T.N. Tozer. *Clinical Pharmacokinetics and Pharmacodynamics: Concepts and Applications*. 4th edition. D.B. Troy. Lippincott Williams and Wilkins. Philadelphia, PA 19106. pp. 199. 1984. #### 66 [T. Sawamato, S. Haruta, Y. Kurosaki, K. Higaki, and T. Kimura. *Prediction of the Plasma Concentration Profiles of Orally Administered Drugs in Rats on the Basis of Gastrointestinal Transit Kinetics and Absorbability*. Journal of Pharmaceutical Pharmacology. 49. 450-457. 1997.](https://pubmed.ncbi.nlm.nih.gov/9232547) #### 67 [J. Schlender. A report including the description of the physiology base of the Japanese population implemented in PK-Sim®.](https://github.com/Open-Systems-Pharmacology/OSPSuite.Documentation/blob/master/Japanese_Population/Report.md) #### 68 [W. Schmitt. *General approach for the calculation of tissue to plasma partition coefficients*. Toxicology In Vitro. 22(2). 457-67. 2008.](https://pubmed.ncbi.nlm.nih.gov/17981004) #### 69 [W. Schmitt and S. Willmann. *Physiology-based pharmacokinetic modeling: ready to be used*. Drug Discov Today. 2. 125-132. 2005.](https://pubmed.ncbi.nlm.nih.gov/24981765) #### 70 [L. F. Shampine. *Solving ODEs and DDEs with residual control*. Appl. Num. Math.. 52. 113-127. 2005.](https://www.sciencedirect.com/science/article/abs/pii/S0168927404001187) #### 71 [P. Sidhu, H. T. Peng, B. Cheung, and A. Edginton. *Simulation of differential drug pharmacokinetics under heat and exercise stress using a physiologically based pharmacokinetic modeling approach*. Can J Physiol Pharmacol. 365-82. 89(5). 2011.](https://pubmed.ncbi.nlm.nih.gov/21627485) #### 72 [R.B. Silvermann. *Mechanism-based enzyme inhibitors*. Methods in Enzymology. 249. 1995.](https://pubmed.ncbi.nlm.nih.gov/7791614) #### 73 [A. Strougo, T. Eissing, A. Yassen, S. Willmann, M. Danhof, and J. Freijer. *First dose in children: physiological insights into pharmacokinetic scaling approaches and their implications in paediatric drug development*. J Pharmacokinet Pharmacodyn. 2012.](https://pubmed.ncbi.nlm.nih.gov/22311388) #### 74 G. Tanaka and H. Kawamura. *Anatomical and physiological characteristics for Asian reference man: Male and female of different ages: Tanaka model*. Division of Radioecology. National Institute of Radiological Sciences. Hitachinaka 311-12 Japan. Report Number NIRS-M-115. 1996. #### 75 [A. Terenji, S. Willmann, J. Osterholz, P. Hering, and H. J. Schwarzmaier. *Measurement of the coagulation dynamics of bovine liver using the modified microscopic Beer-Lambert law*. Lasers Surg Med. 365-70. 36(5). 2005.](https://pubmed.ncbi.nlm.nih.gov/15825206) #### 76 [F. P. Theil, T. W. Guentert, S. Haddad, and P. Poulin. *Utility of Physiologically Based Pharmacokinetic Models to Drug Development and Rational Drug Discovery Candidate Selection*. Toxicology Letters. 138. 29-49. 2003.](https://pubmed.ncbi.nlm.nih.gov/12559691) #### 77 [K. Thelen and J.B. Dressman. *Cytochrome P450-mediated metabolism in the human gut wall*. Journal of Pharmacokinetics and Pharmacodynamics. 61(5). 541-58. 2009.](https://pubmed.ncbi.nlm.nih.gov/19405992) #### 78 [K. Thelen, E. Jantratid, J. B. Dressman, J. Lippert, and S. Willmann. *Analysis of nifedipine absorption from soft gelatin capsules using PBPK modeling and biorelevant dissolution testing*. J Pharm Sci. 2899-904. 99(6). 2010.](https://pubmed.ncbi.nlm.nih.gov/20014280) #### 79 [K. Thelen, K. Coboeken, S. Willmann, R. Burghaus, J. B. Dressman, and J. Lippert. *Evolution of a detailed physiological model to simulate the gastrointestinal transit and absorption process in humans, part 1: oral solutions*. J Pharm Sci. 5324-45. 100(12). 2011.](https://pubmed.ncbi.nlm.nih.gov/21993815) #### 80 [K. Thelen, K. Coboeken, S. Willmann, J. B. Dressman, and J. Lippert. *Evolution of a detailed physiological model to simulate the gastrointestinal transit and absorption process in humans, part II: extension to describe performance of solid dosage forms*. J Pharm Sci. 1267-80. 101(3). 2012.](https://pubmed.ncbi.nlm.nih.gov/22125236) #### 81 [K. Thelen, K. Coboeken, Y. Jia, J.B. Dressman, S. Willmann. *Dynamically simulating the effect of food on gastric emptying using a detailed physiological model for gastrointestinal transit and absorption*. PAGE meeting 2012. Venice, Italy. 2012.](https://www.page-meeting.org/default.asp?abstract=2355) #### 82 [Third National Health and Nutrition Examination Survey, (NHANES III). 1997. National Center for Health Statistics Hyattsville, MD 20782](http://www.cdc.gov/nchs/nhanes.htm) #### 83 [Expressed Sequence Tags (EST) from UniGene. 2010. National Center for Biotechnology Information (NCBI)](https://ftp.ncbi.nlm.nih.gov/repository/UniGene/) #### 84 [Annals of the ICRP. Basic Anatomical and Physiological Data for Use in Radiological Protection: Reference Values. J. Valentin. Vol. 32 (3-4). 2002.](https://pubmed.ncbi.nlm.nih.gov/14506981) #### 85 [P. H. van der Graaf and N. Benson. *Systems pharmacology: bridging systems biology and pharmacokineticspharmacodynamics (PKPD) in drug discovery and development*. Pharm Res. 1460-4. 28(7). 2011.](https://pubmed.ncbi.nlm.nih.gov/21560018) #### 86 [B. van Ommen, J. de Jongh, J. van de Sandt, B. Blaauboer, E. Hissink, J. Bogaards, and P. Bladeren. *Computer-aided Biokinetic Modelling Combined with In Vitro Data*. Toxicology In Vitro. 9. 537-542. 1995.](https://pubmed.ncbi.nlm.nih.gov/20650125) #### 87 [M. Vossen, M. Sevestre, C. Niederalt, I. J. Jang, S. Willmann, and A. N. Edginton. *Dynamically simulating the interaction of midazolam and the CYP3A4 inhibitor itraconazole using individual coupled whole-body physiologically-based pharmacokinetic (WB-PBPK) models*. Theor Biol Med Model. 13. 4. 2007.](https://pubmed.ncbi.nlm.nih.gov/17386084) #### 88 [W. Wang, E. Q. Wang, and J.P. Balthasar. *Monoclonal Antibody Pharmacokinetics and Pharmacodynamics*. Clin Pharmacol Ther.. 548-58. 84(5). 2008.](https://pubmed.ncbi.nlm.nih.gov/18784655) #### 89 [O. Weber, S. Willmann, H. Bischoff, V. Li, A. Vakalopoulos, K. Lustig, F. T. Hafner, R. Heinig, C. Schmeck, and K. Buehner. *Prediction of a potentially effective dose in humans for BAY 60-5521, a potent inhibitor of cholesteryl ester transfer protein (CETP) by allometric species scaling and combined pharmacodynamic and physiologically-based pharmacokinetic modelling*. Br J Clin Pharmacol. 219-31. 73(2). 2012.](https://pubmed.ncbi.nlm.nih.gov/21762205) #### 90 [S. Willmann, H. J. Schwarzmaier, A. Terenji, I. V. Yaroslavsky, and P. Hering. *Quantitative microspectrophotometry in turbid media*. Appl Opt. 4904-13. 38(22). 1999.](https://pubmed.ncbi.nlm.nih.gov/18323981) #### 91 [S. Willmann, A. Terenji, H. Busse, I. V. Yaroslavsky, A. N. Yaroslavsky, H. J. Schwarzmaier, and P. Hering. *Scattering delay time of Mie scatterers determined from steady-state and time-resolved optical spectroscopy*. J Opt Soc Am A Opt Image Sci Vis. 745-9. 17(4). 2000.](https://pubmed.ncbi.nlm.nih.gov/10757182) #### 92 [S. Willmann, J. Lippert, M. Sevestre, J. Solodenko, F. Fois, and W. Schmitt. PK-Sim®: A physiologically based pharmacokinetic 'whole-body' model. Biosilico. 1. 121-124. 2003.](https://www.sciencedirect.com/science/article/abs/pii/S1478538203023424) #### 93 [S. Willmann, W. Schmitt, J. Keldenich, and J. B. Dressman. *A Physiologic Model for Simulating Gastrointestinal Flow and Drug Absorption in Rats*. Pharmaceutical Research. 20. 1766-1771. 2003.](https://pubmed.ncbi.nlm.nih.gov/14661920) #### 94 [S. Willmann, A. Terenji, J. Osterholz, J. Meister, P. Hering, and H.J. Schwarzmaier. *Small-volume frequency-domain oximetry: phantom experiments and first in vivo results*. J Biomed Opt. 618-28. 8(4). 2003.](https://pubmed.ncbi.nlm.nih.gov/14563199) #### 95 [S. Willmann, W. Schmitt, J. Keldenich, J. Lippert, and J. B. Dressman. *A Physiological Model for the Estimation of Fraction Dose Absorbed in Humans*. Journal of Medical Chemistry. 47. 4022-4031. 2004.](https://pubmed.ncbi.nlm.nih.gov/15267240) #### 96 [S. Willmann, J. Lippert, and W. Schmitt. *From physicochemistry to absorption and distribution: predictive mechanistic modelling and computational tools*. Expert Opinion on Drug Metabolism and Toxicology. 1. 159-168. 2005.](https://pubmed.ncbi.nlm.nih.gov/16922658) #### 97 [S. Willmann, K. Hoehn, A. N. Edginton, M. Sevestre, J. Solodenko, W. Weiss, J. Lippert, and W. Schmitt. *Development of a physiologically-based whole-body population model for assessing the influence of individual variability on the pharmacokinetics of drugs*. Journal of Pharmacokinetics and Pharmacodynamics. 34(3). 401-431. 2007.](https://pubmed.ncbi.nlm.nih.gov/17431751) #### 98 [S. Willmann, A.N. Edginton, and J.B. Dressman. *Development and validation of a physiology-based model for the prediction of oral absorption in monkeys*. Pharmaceutical Research. 24(7). 1275-82. 2007.](https://pubmed.ncbi.nlm.nih.gov/17373575) #### 99 [S. Willmann, A.N. Edginton, M. Kleine-Besten, E. Jantratid, K. Thelen, and J.B. Dressman. *Whole-Body Physiologically-Based Pharmacokinetic Population Modelling of Oral Drug Administration: Inter-Individual Variability of Cimetidine Absorption*. Journal of Pharmacokinetics and Pharmacodynamics. 61. 891-9. 2009.](https://pubmed.ncbi.nlm.nih.gov/19589231) #### 100 [S. Willmann, A.N. Edginton, K. Coboeken, G. Ahr, and J. Lippert. *Risk to the Breast-Fed Neonate From Codeine Treatment to the Mother: A Quantitative Mechanistic Modeling Study*. Clinical Pharmacology and Therapeutics. advance online publication. 2009.](https://pubmed.ncbi.nlm.nih.gov/19710640) #### 101 [S. Willmann. *The in silico Child. Can computer simulations replace clinical pharmacokinetic studies?*. Original: Das In-silico-Child. Konnen Computer-Simulationen klinisch-pharmakokinetische Studien ersetzen?. Pharm Unserer Zeit. 62-7. 38(1). 2009.](https://pubmed.ncbi.nlm.nih.gov/19132649) #### 102 [S. Willmann, K. Thelen, C. Becker, J. B. Dressman, and J. Lippert. *Mechanism-based prediction of particle size-dependent dissolution and absorption: cilostazol pharmacokinetics in dogs*. Eur J Pharm Biopharm. 83-94. 76(1). 2010.](https://pubmed.ncbi.nlm.nih.gov/20554023) #### 103 Y. Wu and F. Kesisoglou. *Immediate Release Oral Dosage Forms: Formulation Screening in the Pharmaceutical Industry*. in: Oral Drug Absorption: Prediction and Assessment. J. J. Dressman. C. Reppas. Informa Healthcare. New York, USA. pp. 323. 2009. #### 104 [J. Yang, M. Jamei, and K. Rowland Yeo. *Theoretical assessment of a new experimental protocol for determining kinetic values describing mechanism (time)-based enzyme inhibition* . European Journal in Pharmaceutical Sciences. 31. 2007.](https://pubmed.ncbi.nlm.nih.gov/17512176) #### 105 [H. Zischka, C. J. Gloeckner, C. Klein, S. Willmann, M. Swiatek-de Lange, and M. Ueffing. *Improved mass spectrometric identification of gel- separated hydrophobic membrane proteins after sodium dodecyl sulfate removal by ion-pair extraction*. Proteomics. 3776-82. 4(12). 2004.](https://pubmed.ncbi.nlm.nih.gov/15540170) #### 106 [Hanke N, Frechen S, Moj D, Britz H, Eissing T, Wendl T, Lehr T. *PBPK models for CYP3A4 and P‐gp DDI prediction: a modeling network of rifampicin, itraconazole, clarithromycin, midazolam, alfentanil and digoxin.*](https://www.ncbi.nlm.nih.gov/pubmed/30091221) #### 107 [Dallmann A, Ince I, Solodenko J, et al. Physiologically Based Pharmacokinetic Modeling of Renally Cleared Drugs in Pregnant Women. Clin Pharmacokinet. 2017;56(12):1525-1541. doi:10.1007/s40262-017-0538-0](https://pubmed.ncbi.nlm.nih.gov/28391404) #### 108 [Dallmann A, Ince I, Meyer M, Willmann S, Eissing T, Hempel G. Gestation-Specific Changes in the Anatomy and Physiology of Healthy Pregnant Women: An Extended Repository of Model Parameters for Physiologically Based Pharmacokinetic Modeling in Pregnancy. Clin Pharmacokinet. 2017;56(11):1303-1330. doi:10.1007/s40262-017-0539-z](https://pubmed.ncbi.nlm.nih.gov/28401479) #### 109 [Dallmann A, Ince I, Coboeken K, Eissing T, Hempel G. A Physiologically Based Pharmacokinetic Model for Pregnant Women to Predict the Pharmacokinetics of Drugs Metabolized Via Several Enzymatic Pathways. Clin Pharmacokinet. 2018;57(6):749-768. doi:10.1007/s40262-017-0594-5](https://pubmed.ncbi.nlm.nih.gov/28924743) #### 110 [Dallmann A, Solodenko J, Ince I, Eissing T. Applied Concepts in PBPK Modeling: How to Extend an Open Systems Pharmacology Model to the Special Population of Pregnant Women. CPT Pharmacometrics Syst Pharmacol. 2018;7(7):419-431. doi:10.1002/psp4.12300](https://pubmed.ncbi.nlm.nih.gov/29569837) #### 111 [Claassen K, Thelen K, Coboeken K, et al. Development of a Physiologically-Based Pharmacokinetic Model for Preterm Neonates: Evaluation with In Vivo Data. *Curr Pharm Des*. 2015;21(39):5688-5698. doi:10.2174/1381612821666150901110533](https://pubmed.ncbi.nlm.nih.gov/26323410) #### 112 [Mavroudis PD, Hermes HE, Teutonico D, Preuss TG, Schneckener S. Development and validation of a physiology-based model for the prediction of pharmacokinetics/toxicokinetics in rabbits. *PLoS One*. 2018;13(3):e0194294. Published 2018 Mar 21. doi:10.1371/journal.pone.0194294](https://pubmed.ncbi.nlm.nih.gov/29561908) #### 113 [Schlender JF, Meyer M, Thelen K, et al. Development of a Whole-Body Physiologically Based Pharmacokinetic Approach to Assess the Pharmacokinetics of Drugs in Elderly Individuals. *Clin Pharmacokinet*. 2016;55(12):1573-1589. doi:10.1007/s40262-016-0422-3](https://pubmed.ncbi.nlm.nih.gov/27351180/) #### 114 [Niederalt C, Kuepfer L, Solodenko J, et al. A generic whole body physiologically based pharmacokinetic model for therapeutic proteins in PK-Sim. *J Pharmacokinet Pharmacodyn*. 2018;45(2):235-257. doi:10.1007/s10928-017-9559-4](https://pubmed.ncbi.nlm.nih.gov/29234936) #### 115 [Lippert J, Burghaus R, Edginton A, et al. Open Systems Pharmacology Community-An Open Access, Open Source, Open Science Approach to Modeling and Simulation in Pharmaceutical Sciences. *CPT Pharmacometrics Syst Pharmacol*. 2019;8(12):878-882. doi:10.1002/psp4.12473](https://pubmed.ncbi.nlm.nih.gov/31671256) #### 116 [Kuepfer L, Niederalt C, Wendl T, et al. Applied Concepts in PBPK Modeling: How to Build a PBPK/PD Model. *CPT Pharmacometrics Syst Pharmacol*. 2016;5(10):516-531. doi:10.1002/psp4.12134](https://pubmed.ncbi.nlm.nih.gov/27653238) #### 117 [EFPIA MID3 Workgroup, Marshall SF, Burghaus R, et al. Good Practices in Model-Informed Drug Discovery and Development: Practice, Application, and Documentation. *CPT Pharmacometrics Syst Pharmacol*. 2016;5(3):93-122. doi:10.1002/psp4.12049](https://pubmed.ncbi.nlm.nih.gov/27069774) #### 118 [Schneckener S, Preuss TG, Kuepfer L, Witt J. A workflow to build PBTK models for novel species. *Arch Toxicol*. 2020;94(11):3847-3860. doi:10.1007/s00204-020-02922-z](https://pubmed.ncbi.nlm.nih.gov/33033842) #### 119 [Ince I, Solodenko J, Frechen S, et al. Predictive Pediatric Modeling and Simulation Using Ontogeny Information. *J Clin Pharmacol*. 2019;59 Suppl 1:S95-S103. doi:10.1002/jcph.1497](https://pubmed.ncbi.nlm.nih.gov/31502689) #### 120 [Sjögren E, Tarning J, Barnes KI, Jonsson EN. A Physiologically-Based Pharmacokinetic Framework for Prediction of Drug Exposure in Malnourished Children. *Pharmaceutics*. 2021;13(2):204. Published 2021 Feb 2. doi:10.3390/pharmaceutics13020204](https://pubmed.ncbi.nlm.nih.gov/33540928) #### 121 [Frechen S, Solodenko J, Wendl T, et al. A generic framework for the physiologically-based pharmacokinetic platform qualification of PK-Sim and its application to predicting cytochrome P450 3A4-mediated drug-drug interactions. CPT Pharmacometrics Syst Pharmacol. 2021;10(6):633-644. doi:10.1002/psp4.12636](https://pubmed.ncbi.nlm.nih.gov/33946131) #### 122 [Paul R.V. Malik, Cindy H.T. Yeung, Shams Ismaeil, Urooj Advani, Sebastian Djie, Andrea N. Edginton. A Physiological Approach to Pharmacokinetics in Chronic Kidney Disease](https://accp1.onlinelibrary.wiley.com/doi/full/10.1002/jcph.1713) #### 123 [FDA Meeting: Development of Best Practices in Physiologically Based Pharmacokinetic Modeling to Support Clinical Pharmacology Regulatory Decision-Making](https://www.fda.gov/drugs/news-events-human-drugs/development-best-practices-physiologically-based-pharmacokinetic-modeling-support-clinical) #### 124 [Peters and Dolgos. Requirements to Establishing Confidence in Physiologically Based Pharmacokinetic (PBPK) Models and Overcoming Some of the Challenges to Meeting Them.](https://doi.org/10.1007/s40262-019-00790-0) #### 125 [FDA, Center for Drug Evaluation and. 2019. “Physiologically Based Pharmacokinetic Analyses — Format and Content Guidance for Industry.” U.S. Food and Drug Administration. October 18, 2019.](http://www.fda.gov/regulatory-information/search-fda-guidance-documents/physiologically-based-pharmacokinetic-analyses-format-and-content-guidance-industry) #### 126 [EMA Guideline: Guideline on the qualification and reporting of physiologically based pharmacokinetic (PBPK) modelling and simulation.](https://www.ema.europa.eu/en/reporting-physiologically-based-pharmacokinetic-pbpk-modelling-simulation-scientific-guideline) #### 127 [Frechen, S., Rostami-Hodjegan, A. Quality Assurance of PBPK Modeling Platforms and Guidance on Building, Evaluating, Verifying and Applying PBPK Models Prudently under the Umbrella of Qualification: Why, When, What, How and By Whom?. Pharm Res 39, 1733–1748 (2022)](https://doi.org/10.1007/s11095-022-03250-w) #### 128 [Shebley et al. Physiologically Based Pharmacokinetic Model Qualification and Reporting Procedures for Regulatory Submissions: A Consortium Perspective.](https://doi.org/10.1002/cpt.1013) #### 129 [Miller et al. Physiologically Based Pharmacokinetic Modelling for First‐In‐Human Predictions: An Updated Model Building Strategy Illustrated with Challenging Industry Case Studies.](https://doi.org/10.1007/s40262-019-00741-9) #### 130 [OECD (2021), Guidance document on the characterisation, validation and reporting of Physiologically Based Kinetic (PBK) models for regulatory purposes, OECD Series on Testing and Assessment, No. 331, OECD Publishing, Paris](https://www.oecd.org/content/dam/oecd/en/publications/reports/2021/02/guidance-document-on-the-characterisation-validation-and-reporting-of-physiologically-based-kinetic-pbk-models-for-regulatory-purposes_670da2f4/d0de241f-en.pdf) #### 131 [Calvier, Elisa A. M., Thu Thuy Nguyen, Trevor N. Johnson, Amin Rostami-Hodjegan, Dick Tibboel, Elke H. J. Krekels, and Catherijne A. J. Knibbe. 2018. “Can Population Modelling Principles Be Used to Identify Key PBPK Parameters for Paediatric Clearance Predictions? An Innovative Application of Optimal Design Theory.” *Pharmaceutical Research* 35 (11): 209.](https://doi.org/10.1007/s11095-018-2487-1) #### 132 [Dallmann, André, Ibrahim Ince, Juri Solodenko, Michaela Meyer, Stefan Willmann, Thomas Eissing, and Georg Hempel. 2017. “Physiologically Based Pharmacokinetic Modeling of Renally Cleared Drugs in Pregnant Women.” Clinical Pharmacokinetics 56 (12): 1525–41.](https://doi.org/10.1007/s40262-017-0538-0) #### 133 [Doki, Kosuke, Adam S. Darwich, Nikunjkumar Patel, and Amin Rostami-Hodjegan. 2017. “Virtual Bioequivalence for Achlorhydric Subjects: The Use of PBPK Modelling to Assess the Formulation-Dependent Effect of Achlorhydria.” European Journal of Pharmaceutical Sciences 109 (November): 111–20.](https://doi.org/10.1016/j.ejps.2017.07.035) #### 134 [Fendt, Rebekka, Hofmann, Ute, Schneider, Annika R.P., Schaeffeler, Elke, Burghaus, Rolf, et al. 2021. “Data-Driven Personalization of a Physiologically Based Pharmacokinetic Model for Caffeine: A Systematic Assessment” CPT: Pharmacometrics & Systems Pharmacology.](https://doi.org/10.1002/psp4.12646) #### 135 [Grimstein, Manuela, Yuching Yang, Xinyuan Zhang, Joseph Grillo, Shiew-Mei Huang, Issam Zineh, and Yaning Wang. 2019. “Physiologically Based Pharmacokinetic Modeling in Regulatory Science: An Update From the U.S. Food and Drug Administration’s Office of Clinical Pharmacology.” Journal of Pharmaceutical Sciences 108 (1): 21–25.](https://doi.org/10.1016/j.xphs.2018.10.033) #### 136 [Heimbach, Tycho, Yuan Chen, Jun Chen, Vaishali Dixit, Neil Parrott, Sheila Annie Peters, Italo Poggesi, et al. 2020. “Physiologically-Based Pharmacokinetic Modeling in Renal and Hepatic Impairment Populations: A Pharmaceutical Industry Perspective.” Clinical Pharmacology & Therapeutics n/a (n/a).](https://doi.org/10.1002/cpt.2125) #### 137 [Kuemmel, Colleen, Yan, Yuching, Zhang, Xiyuan, Florian, Jeffry, Zhu, Hao et al. 2019.” Consideration of a Credibility Assessment Framework in Model-Informed Drug Development: Potential Application to PBPK Modeling and Simulation” CPT: Pharmacometrics & Systems Pharmacology.](https://doi.org/10.1002/psp4.12479) #### 138 [Lin, Wen, Jing-He Yan, Tycho Heimbach, and Handan He. 2018. “Pediatric Physiologically Based Pharmacokinetic Model Development: Current Status and Challenges.” Current Pharmacology Reports 4 (6): 491–501.](https://doi.org/10.1007/s40495-018-0162-1) #### 139 [Loisios-Konstantinidis, Ioannis, Rodrigo Cristofoletti, Nikoletta Fotaki, David B. Turner, and Jennifer Dressman. 2020. “Establishing Virtual Bioequivalence and Clinically Relevant Specifications Using in Vitro Biorelevant Dissolution Testing and Physiologically-Based Population Pharmacokinetic Modeling. Case Example: Naproxen.” European Journal of Pharmaceutical Sciences 143 (February): 105170.](https://doi.org/10.1016/j.ejps.2019.105170) #### 140 [Loisios-Konstantinidis, Ioannis, Bart Hens, Amitava Mitra, Sarah Kim, Chang Chiann, and Rodrigo Cristofoletti. 2020. “Using Physiologically Based Pharmacokinetic Modeling to Assess the Risks of Failing Bioequivalence Criteria: A Tale of Two Ibuprofen Products.” The AAPS Journal 22 (5): 113.](https://doi.org/10.1208/s12248-020-00495-4) #### 141 [Morcos, Peter N., Yumi Cleary, Carolina Sturm‐Pellanda, Elena Guerini, Markus Abt, Massimiliano Donzelli, Faye Vazvaei, Bogdana Balas, Neil Parrott, and Li Yu. 2018. “Effect of Hepatic Impairment on the Pharmacokinetics of Alectinib.” The Journal of Clinical Pharmacology 58 (12): 1618–28.](https://doi.org/10.1002/jcph.1286) #### 142 [Peters, Sheila Annie, and Hugues Dolgos. 2019. “Requirements to Establishing Confidence in Physiologically Based Pharmacokinetic (PBPK) Models and Overcoming Some of the Challenges to Meeting Them.” Clinical Pharmacokinetics 58 (11): 1355–71.](https://doi.org/10.1007/s40262-019-00790-0) #### 143 [Rimmler, Christer, Christian Lanckohr, Ceren Akamp, Dagmar Horn, Manfred Fobker, Karsten Wiebe, Bassam Redwan, Bjoern Ellger, Robin Koeck, and Georg Hempel. 2019. “Physiologically Based Pharmacokinetic Evaluation of Cefuroxime in Perioperative Antibiotic Prophylaxis.” British Journal of Clinical Pharmacology 85 (12): 2864–77.](https://doi.org/10.1111/bcp.14121) #### 144 [Tan, Ming-Liang, Ping Zhao, Lei Zhang, Yunn-Fang Ho, Manthena V. S. Varma, Sibylle Neuhoff, Thomas D. Nolin, Aleksandra Galetin, and Shiew-Mei Huang. 2019. “Use of Physiologically Based Pharmacokinetic Modeling to Evaluate the Effect of Chronic Kidney Disease on the Disposition of Hepatic CYP2C8 and OATP1B Drug Substrates.” Clinical Pharmacology & Therapeutics 105 (3): 719–29.](https://doi.org/10.1002/cpt.1205) #### 145 [Türk, Denise, Nina Hanke, and Thorsten Lehr. 2020. “A Physiologically-Based Pharmacokinetic Model of Trimethoprim for MATE1, OCT1, OCT2, and CYP2C8 Drug–Drug–Gene Interaction Predictions.” Pharmaceutics 12 (11): 1074.](https://doi.org/10.3390/pharmaceutics12111074) #### 146 [Wagner, C., P. Zhao, Y. Pan, V. Hsu, J. Grillo, S. M. Huang, and V. Sinha. 2015. “Application of Physiologically Based Pharmacokinetic (PBPK) Modeling to Support Dose Selection: Report of an FDA Public Workshop on PBPK.” CPT: Pharmacometrics & Systems Pharmacology 4 (4): 226–30.](https://doi.org/10.1002/psp4.33) #### 147 [Yun, Yejin Esther, and Andrea N. Edginton. 2019. “Model Qualification of the PK-Sim® Pediatric Module for Pediatric Exposure Assessment of CYP450 Metabolized Compounds.” Journal of Toxicology and Environmental Health. Part A 82 (14): 789–814.](https://doi.org/10.1080/15287394.2019.1652215) #### 148 [Zhao, P, L Zhang, J A Grillo, Q Liu, J M Bullock, Y J Moon, P Song, et al. 2011. “Applications of Physiologically Based Pharmacokinetic (PBPK) Modeling and Simulation During Regulatory Review.” Clinical Pharmacology & Therapeutics 89 (2): 259–67.](https://doi.org/10.1038/clpt.2010.298) #### 149 [Zhou, Diansong, Terry Podoll, Yan Xu, Ganesh Moorthy, Karthick Vishwanathan, Joseph Ware, J. Greg Slatter, and Nidal Al‐Huniti. 2019. “Evaluation of the Drug–Drug Interaction Potential of Acalabrutinib and Its Active Metabolite, ACP-5862, Using a Physiologically-Based Pharmacokinetic Modeling Approach.” CPT: Pharmacometrics & Systems Pharmacology 8 (7): 489–99.](https://doi.org/10.1002/psp4.12408) #### 150 [Zhuang, Xiaomei, and Chuang Lu. 2016. “PBPK Modeling and Simulation in Drug Research and Development.” Acta Pharmaceutica Sinica. B 6 (5): 430–40.](https://doi.org/10.1016/j.apsb.2016.04.004) #### 151 Kuemmel, C., Yang, Y., Zhang, X., Florian, J., Zhu, H., Tegenge, M., Huang, S.-M., Wang, Y., Morrison, T., & Zineh, I. (2020). Consideration of a Credibility Assessment Framework in Model-Informed Drug Development: Potential Application to Physiologically-Based Pharmacokinetic Modeling and Simulation. CPT: Pharmacometrics & Systems Pharmacology, 9(1), 21–28 #### 152 [Rüdesheim, S., Wojtyniak, J.-G., Selzer, D., Hanke, N., Mahfoud, F., Schwab, M., & Lehr, T. (2020). Physiologically Based Pharmacokinetic Modeling of Metoprolol Enantiomers and α-Hydroxymetoprolol to Describe CYP2D6 Drug-Gene Interactions. Pharmaceutics, 12(12).](https://doi.org/10.3390/pharmaceutics12121200) #### 153 Utsey, K., Gastonguay, M. S., Russell, S., Freling, R., Riggs, M. M., & Elmokadem, A. (2020). Quantification of the Impact of Partition Coefficient Prediction Methods on Physiologically Based Pharmacokinetic Model Output Using a Standardized Tissue Composition. Drug Metabolism and Disposition: The Biological Fate of Chemicals, 48(10), 903–916. #### 154 [Peters and Dolgos. Requirements to Establishing Confidence in Physiologically Based Pharmacokinetic (PBPK) Models and Overcoming Some of the Challenges to Meeting Them.](https://doi.org/10.1007/s40262-019-00790-0) #### 155 McNally, K., Cotton, R., & Loizou, G. D. (2011). A Workflow for Global Sensitivity Analysis of PBPK Models. Frontiers in Pharmacology, 2, 31. #### 156 Peters, S. A. (Ed.). (2012). Variability, Uncertainty, and Sensitivity Analysis. In Physiologically-Based Pharmacokinetic (PBPK) Modeling and Simulations (Vol. 120, pp. 161–181). John Wiley & Sons, Inc. #### 157 Hsieh, N.-H., Reisfeld, B., Bois, F. Y., & Chiu, W. A. (2018). Applying a Global Sensitivity Analysis Workflow to Improve the Computational Efficiencies in Physiologically-Based Pharmacokinetic Modeling. Frontiers in Pharmacology, 9, 588. #### 158 Zhang, X.-Y., Trame, M. N., Lesko, L. J., & Schmidt, S. (2015). Sobol Sensitivity Analysis: A Tool to Guide the Development and Evaluation of Systems Pharmacology Models. CPT: Pharmacometrics & Systems Pharmacology, 4(2), 69–79. #### 159 [Miller, Neil A., Micaela B. Reddy, Aki T. Heikkinen, Viera Lukacova, and Neil Parrott. 2019. “Physiologically Based Pharmacokinetic Modelling for First-In-Human Predictions: An Updated Model Building Strategy Illustrated with Challenging Industry Case Studies.” Clinical Pharmacokinetics, February.](https://doi.org/10.1007/s40262-019-00741-9) #### 160 [Cho, Hyun-Jong, Ji-Eon Kim, Dae-Duk Kim, and In-Soo Yoon. 2014. “In Vitro-in Vivo Extrapolation (IVIVE) for Predicting Human Intestinal Absorption and First-Pass Elimination of Drugs: Principles and Applications.” Drug Development and Industrial Pharmacy 40 (8): 989–98.](https://doi.org/10.3109/03639045.2013.831439) #### 161 [Poulin, Patrick, Hannah M. Jones, Rhys Do Jones, James W.T. Yates, Christopher R. Gibson, Jenny Y. Chien, Barbara J. Ring, et al. 2011. “PhRMA CPCDC Initiative on Predictive Models of Human Pharmacokinetics, Part 1: Goals, Properties of the Phrma Dataset, and Comparison with Literature Datasets.” Journal of Pharmaceutical Sciences 100 (10): 4050–73.](https://doi.org/10.1002/jps.22554) #### 162 [Berezhkovskiy, Leonid M. 2004. “Volume of Distribution at Steady State for a Linear Pharmacokinetic System with Peripheral Elimination.” Journal of Pharmaceutical Sciences 93 (6): 1628–40.](https://doi.org/10.1002/jps.20073) #### 163 [Poulin, P., and F. P. Theil. 2000. “A Priori Prediction of Tissue:Plasma Partition Coefficients of Drugs to Facilitate the Use of Physiologically-Based Pharmacokinetic Models in Drug Discovery.” Journal of Pharmaceutical Sciences 89 (1): 16–35.](https://doi.org/10.1002/%28sici%291520-6017%28200001%2989:1%3C16::aid-jps3%3E3.0.co;2-e) #### 164 [Rodgers, Trudy, David Leahy, and Malcolm Rowland. 2005. “Physiologically Based Pharmacokinetic Modeling 1: Predicting the Tissue Distribution of Moderate-to-Strong Bases.” Journal of Pharmaceutical Sciences 94 (6): 1259–76.](https://doi.org/10.1002/jps.20322) #### 165 [Benet, Leslie Z., and Jasleen K. Sodhi. 2020. “Investigating the Theoretical Basis for In Vitro–In Vivo Extrapolation (IVIVE) in Predicting Drug Metabolic Clearance and Proposing Future Experimental Pathways.” The AAPS Journal 22 (5): 120.](https://doi.org/10.1208/s12248-020-00501-9) #### 166 [Kumar, Vineet, Jia Yin, Sarah Billington, Bhagwat Prasad, Colin D. A. Brown, Joanne Wang, and Jashvant D. Unadkat. 2018. “The Importance of Incorporating OCT2 Plasma Membrane Expression and Membrane Potential in IVIVE of Metformin Renal Secretory Clearance.” Drug Metabolism and Disposition: The Biological Fate of Chemicals 46 (10): 1441–45.](https://doi.org/10.1124/dmd.118.082313) #### 167 [Trapa, Patrick E., Matthew D. Troutman, Thomas Y. Lau, Travis T. Wager, Tristan S. Maurer, Nandini C. Patel, Mark A. West, et al. 2019. “In Vitro–In Vivo Extrapolation of Key Transporter Activity at the Blood–Brain Barrier.” Drug Metabolism and Disposition 47 (4): 405–11.](https://doi.org/10.1124/dmd.118.083279) #### 168 [Kuepfer, L, C Niederalt, T Wendl, J-F Schlender, S Willmann, J Lippert, M Block, T Eissing, and D Teutonico. 2016. “Applied Concepts in PBPK Modeling: How to Build a PBPK/PD Model: Applied Concepts in PBPK Modeling.” CPT: Pharmacometrics & Systems Pharmacology 5 (10): 516–31.](https://doi.org/10.1002/psp4.12134) #### 169 [Marshall, S. F., R. Burghaus, V. Cosson, S. Y. A. Cheung, M. Chenel, O. DellaPasqua, N. Frey, et al. 2016. “Good Practices in Model-Informed Drug Discovery and Development: Practice, Application, and Documentation.” CPT: Pharmacometrics & Systems Pharmacology 5 (3): 93–122.](https://doi.org/10.1002/psp4.12049) #### 170 [Tan, Yu-Mei, Melissa Chan, Amechi Chukwudebe, Jeanne Domoradzki, Jeffrey Fisher, C. Eric Hack, Paul Hinderliter, et al. 2020. “PBPK Model Reporting Template for Chemical Risk Assessment Applications.” Regulatory Toxicology and Pharmacology 115 (August): 104691.](https://doi.org/10.1016/j.yrtph.2020.104691) #### 171 [Schaller, S., Willmann, S., Lippert, J., Schaupp, L., Pieber, T., Schuppert, A. and Eissing, T. (2013), A Generic Integrated Physiologically based Whole-body Model of the Glucose-Insulin-Glucagon Regulatory System. CPT: Pharmacometrics & Systems Pharmacology, 2: 1-10 65.](https://doi.org/10.1038/psp.2013.40) #### 172 [Balazki, P., Schaller, S., Eissing, T. and Lehr, T. (2018), A Quantitative Systems Pharmacology Kidney Model of Diabetes Associated Renal Hyperfiltration and the Effects of SGLT Inhibitors. CPT Pharmacometrics Syst. Pharmacol., 7: 788-797.](https://doi.org/10.1002/psp4.12359) #### 173 [Willmann S, Schmitt W, Keldenich J, Lippert J, Dressman JB. A physiological model for the estimation of the fraction dose absorbed in humans. J Med Chem. 2004;47(16):4022–4031.](https://doi.org/10.1021/jm030999b) # README This manual describes the [Open Systems Pharmacology Suite](https://www.open-systems-pharmacology.org). 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. Documentation for the developers of the Open Systems Pharmacology Suite and more technical details are provided [here](https://dev.open-systems-pharmacology.org/). 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](/v12/mechanistic-modeling-of-pharmacokinetics-and-dynamics/modeling-concepts/modeling-concepts-pbpk-modeling-systems-biology) ## 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](/v12/open-systems-pharmacology-suite/modules-philsophy-building-blocks) ## 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®](/v12/working-with-pk-sim/pk-sim-documentation/pk-sim-quick-guide) ## Working with MoBi® MoBi® focusing on modular model customization and extension as well as on pharmacodynamics in "Working with MoBi®". [Go to: Working with MoBi®](/v12/working-with-mobi/mobi-documentation/first-steps) ## 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](/v12/shared-tools-and-example-workflows/features-of-tables) ## Working with R The interfaces to the common computing environment R is described in "Working with R". [Go to: Working with R](/v12/working-with-r/introduction-ospsuite-r) # Open Systems Pharmacology Suite Manual & Copyright Version 12 Update 1 Publication date September 2025 Copyright © 2025 [Open Systems Pharmacology Community](/v12/references/references#115) The manual is provided “as is” without expressed or implied warranty. **Trademark information:** All trademarks within this manual belong to their legitimate owners. The Open Systems Pharmacology Suite uses the CVODES solver: Copyright (c) 2002-2021, Lawrence Livermore National Security. Produced at the Lawrence Livermore National Laboratory. Written by A.C. Hindmarsh, D.R. Reynolds, R. Serban, C.S. Woodward, D. J. Gardner, S.D. Cohen, A.G. Taylor, S. Peles, L.E. Banks, and D. Shumaker. UCRL-CODE-155950 (CVODES) All rights reserved. Please, refer to the LLNL website for detailed information on licensing: * * Internet: * Support: * # How to Contribute Welcome to the [docs.open-systems-pharmacology.org](http://docs.open-systems-pharmacology.org) Contributor guide! The documentation for the Open Systems Pharmacology Suite is open source and hosted on GitHub. Despite all the efforts to maintain and update the documentation, there will always be small grammar and spelling errors sliding through the cracks as well as sections of the documentation that are not clear enough, missing or outdated. While you can create issues in the [docs repository](https://github.com/Open-Systems-Pharmacology/docs/issues) to report those errors or omissions, it will often be faster and easier to submit your edits directly to be reviewed by the documentation core team. This guide aims at describing the workflow to contribute to the documentation. ## Requirements The only requirement to contribute to the documentation is to have a GitHub account. If you do not have an account, you can [create one](https://github.com/join) for free in a few seconds. ## Edit of existing documents Each page available on the docs website corresponds to a file hosted on GitHub that can be edited. Clicking on the `Edit on GitHub` button will take you to the source file on GitHub.![Edit on GitHub](/files/94ntReu9avomjsnCzbPw) Next, click the pencil icon, as shown in the following figure to edit the article.![Edit](/files/bdj129CJjxHAldiOZYs9) {% hint style="info" %} If the pencil icon is grayed out, you need to login to your GitHub account. {% endhint %} {% hint style="info" %} Make your changes in the web editor. Formatting of the documentation is based on the so called **Markdown** syntax. The description of this lightweight and easy-to-use syntax can be found [here](https://guides.github.com/features/mastering-markdown/). You can click the Preview changes tab to check formatting of your change. {% endhint %} Once you are done with your changes, scroll to the bottom of the page. Enter a title and description for your edits and click `Propose file change` as shown in the following figure: ![Propose file change](/files/Urgm7Dt4X6KloZq9MOwa) Now that you have proposed your changes, you need to ask the documentation core team to incorporate them into the documentation. This is done using something called a **pull request**. When you clicked on `Propose file change` in the figure above (and on `Create pull request` after that), you should have been taken to a new page that looks like the following figure: ![Open pull request](/files/TScgRrC3hgTxuqEu3PvV) Review the title and the description for the pull request, and then click `Create pull request`. That's it! The documentation core team will be notified and review your changes. You may get some feedback requesting changes if you made larger changes. ## Adding new content The process is slightly more complicated as you need to create a new content file and incorporate it into the existing documentation. We would be happy to help you do that if you need some support. Simply open an issue in the docs repo describing what you want to add and where and we'll get in touch with you. ## Rich content ### Note, hints and callout Provides a great way to bring the reader's attention to specific elements. By surrounding your text with `{ % hint style="xxx" %}` and `{ % endhint %}`, a visual clue will be created for your content, making it pop out For example: using the style `note`, we can create the following visual element {% hint style="info" %} This is a note {% endhint %} Available styles are: * tip * note * warning * info # Best Practices # Introduction The versatile nature of physiologically based pharmacokinetic (PBPK) modeling facilitates many opportunities of application but at the same time also for different approaches in terms of execution. This inevitably introduces the questions on way of working and best practices. How should model development, including challenges addressed and assumptions made, be conducted and reported? How should analyses be performed at different stages in drug development to ensure robust results with confidence, reproducibility and traceability? To guide the users of the OSP-Suite we here present our view on best practices for PBPK modeling. The material is categorized under the sections Development, Evaluation, Application\&Simulation and Documentation including a repository of relevant literature to facilitate further reading on the topic. ![Guide to PBPK model development, evalution, simulations and documentation](/files/n1kRTt7hazP81AiosuFx) To note, there are a number of existing review, overview, tutorial, and guidances available to the PBPK Community. This site is not intended to rewrite those materials but instead to serve as a landing page for individuals seeking to learn or to branch further into PBPK modeling. A sampling of existing learning content is listed below: \[[123](/v12/references/references#123)] - \[[130](/v12/references/references#130)] # Model Development Prior to starting on model development, a requirements analysis should be conducted to assess and outline a model development strategy: * the model purpose, i.e. its context of use which should include * Organism / population characteristics (biometrics, genotype, disease state, …) and the * Experimental design * the observed data (e.g., QSA/PR, in-vitro, or in-vivo) available for model development * Non-clinical & clinical data considerations, e.g., would it help the model development of a human PBPK model to develop an animal PBPK model (e.g. for FIM or if no IV data was collected in humans but in animals)? * Individuals data vs population mean data: how will this impact model evaluation and qualification (variability and uncertainty assessments (Considered in Sections “3. Model Evaluation” and “4. Model Applications”))) * and the model evaluation & qualification strategy (Section “Model Evaluation”) This requirements analysis should then be condensed into specifications (i.e., a strategy) for model development & qualification and documented within an analysis plan (see Figure1). ![Model development](/files/aFtHBvk9bwmW8g3WOCOR) Figure 1: Predict, Learn, and Confirm cycle in IVIVE-PBPK model development (adopted from \[[168](/v12/references/references#168)]). Availability and quality of data for model development is the key element and has to be judged in the context of use (see “Useful Literature” below). **As an example:** data quality, e.g. input parameters for compound PK properties such as fraction unbound in plasma (fup) may have been precisely measured or only predicted with some uncertainty through QSPR models. The latter might contain too much uncertainty and not be appropriate in the context of precision dosing estimates for a clinical trial, but might well be suitable for risk assessment in environmental toxicology. Thus, the key is to make yourself aware of the limitations of the available data considering: * accuracy and suitability of data for PBPK model development. * in which systems the data have been collected * fu or lipophilicity measures (partitioning media used, neutral or acid/base compound) * solubility (measured in water or biorelevant media) * dissolution profiles (what apparatus was used and at which pH values). What should not be neglected in the requirements analysis, is the evaluation of the information, data and structure which the PBPK framework and associated databases or “add-on modules” contain. Compound properties and context of use will require decisions and sound qualification on what to select from available options, e.g.: * which partitioning calculation method to choose based on compound properties * how to extend the model (with e.g. “add-on modules” found in modeling literature) if required to fulfill its purpose (i.e., customizing default model equations and structure to account for e.g. specific mechanisms of distribution or new organ compartments not covered by the default PBPK model structure). ## Useful Literature * IVIVE / ADME \[[159](/v12/references/references#159)] * This best practice provides an overview of strategies for first in human prediction based on preclinical modelling. A Review of relevant scientific publications and case examples are provided as well. * Absorption \[[160](/v12/references/references#160)] * This review provides an overview of the determinants of intestinal absorption and first-pass elimination of drugs and focuses on the principles and applications of conventional in vitro–in vivo extrapolation (IVIVE) methods to predict Fabs, FG, and FH in humans. * Distribution \[[161](/v12/references/references#161)], \[[162](/v12/references/references#162)], \[[163](/v12/references/references#163)], \[[164](/v12/references/references#164)] * These papers provide the state of art of mechanistic calculation of steady state tissue:plasma partition coefficients (Kt:p) of organic chemicals in mammalian species was developed. * Metabolism \[[165](/v12/references/references#165)] * Benet and Sodhi proposed future pathways that should be investigated in terms of the relationship to experimentally measured clearance values, rather than model-dependent intrinsic clearance * Transporters & Excretion \[[166](/v12/references/references#166)], \[[167](/v12/references/references#167)] * These data demonstrate the promise of using IVIVE of transporter-mediated drug clearance and highlight the importance of quantifying plasma membrane expression of transporters and utilizing cells that mimic the in vivo mechanism(s) of transport of drugs. ## Further Reading * Data-driven model refinement and qualification (e.g. \[[168](/v12/references/references#168)], \[[124](/v12/references/references#124)] ) * The papers describe a definition of, “qualification”, a how-to work flow, regulatory perspective, and an case example for model refinement * Expansion to a PBPK-QSP Model (Platform) (e.g. \[[171](/v12/references/references#171)], \[[172](/v12/references/references#172)]) * These papers highlight complex integrations of PBPK and PD/QSP for building disease platform level PBPK-QSP models, which include often efficacy-relevant target/receptor kinetics and occupancy, and deposition. # Model Evaluation 1. Get in the “Model Evaluation Mindset”: 1. In your modeling analysis plan, define what questions you are planning to address with the model, i.e. - the “context of use (COU)”. 2. Consider the risk that exists if the model you choose leads to a biased or imprecise result. 3. Define performance requirements that the model will need to achieve for it to be a successful tool for addressing those questions (aka “model credibility”). Gear your model evaluation standards to enable you to determine whether or not your model has achieved the necessary performance requirements. 4. Assess your model credibility as part of the model development. If a candidate model fails to meet requirements, continue to refine. 5. Document evidence of credibility 2. Development of a **Credibility Assessment Framework** \[[151](/v12/references/references#151)] can assist you in defining, conducting, and evaluating the model performance requirements. 1. The Kuemmel et al 2020 paper provides rubrics, e.g., for establishing an assessment of model risk 2. Consider, too, establishing more quantitative criteria for your model, as well. What level of error (MAE, RMSE, MRD, GMFE, ..., sensitivity to uncertainty in parameter values, etc) will be acceptable on which metrics (AUC, Cmax, and/or other). In some cases, for example, you may be able to tolerate a much larger-fold error (if it’s a rough projection of first-in-human dosing) compared with a case where a trial waiver is being considered, e.g., using a PBPK-based DDI projection. These goal posts will likely adjust in a manner consistent with the risk score. ![Model evalution](/files/kSw5l7dksTVta6T3VJip) [**Overview of the ASME V\&V 40 risk‐informed credibility assessment framework**](https://www.ncbi.nlm.nih.gov/pmc/articles/PMC6966181/)**; COU, context of use; V\&V, verification and validation.** 3. Goodness-of-fit diagnostics to consider during model development and for the final model evaluations include the following: 1. Quantitative metrics of predictive performance for exposure endpoints of interest, * e.g., half-life, Cmax and AUC * Precision and bias calculations: RMSE, mean absolute error (MAE), mean relative deviation (MRD) of the predicted plasma concentrations for all observed and the corresponding predicted plasma concentrations as well as geometric mean fold errors (GMFEs) 2. Graphics 1. Overlay of observed and predicted concentration-time profiles. Depending on your focus (include plots on linear scale (e.g. focus on absorption and Cmax) and / or logarithmic scale (e.g. focus on Distribution and elimination)!). \[[152](/v12/references/references#152)], \[[153](/v12/references/references#153)] 2. Observed vs predicted of derived metrics, e.g., Cmax and AUC \[[152](/v12/references/references#152)] 3. Precision and bias metrics (e.g., MAE, RMSE) to compare across models or other methodological approaches \[[153](/v12/references/references#153)] 3. Standards for Model Evaluation Metrics \[[139](/v12/references/references#139)],\[[143](/v12/references/references#143)] 4. Strategies for model development and evaluation 1. Case-based strategies for different application scenarios \[[154](/v12/references/references#154)] 4. Acknowledge parameter value sources and expectations of reliability. Use sensitivity analyses to evaluate the impact that variability or uncertainty in those values might have on model performance: 1. For evaluating, acknowledging, and identifying sources for parameter values, additional considerations include pedigree tables (), and similar approaches, e.g., 1. Braakman S, Paxson R, Tannenbaum S, Gulati A. Visualizing Parameter Source Reliability and Sensitivity for QSP Models. ACoP10 Oct 2019 2. Gulati A, Tannenbaum S. Using visualization to address the reliability of sources of initial parameter values in a Quantitative Systems Pharmacology (QSP) model. ACoP9 October 2018 2. PBPK and QSP modeling requires an understanding and acknowledgement of a priori (structural) and a posteriori (practical) identifiability, as well as characterization of uncertainty in the model parameters. Local and global sensitivity analyses can be used to quantify the influence of parameter variation on predictive performance. 1. A sampling of reviews that provide an overview of these techniques includes: \[[155](/v12/references/references#155)], \[[156](/v12/references/references#156)], \[[157](/v12/references/references#157)], \[[158](/v12/references/references#158)] 2. An open-source example of global sensitivity (Sobol) analysis is available here: 5. Documentation of the model development and evaluations should include evidence from the model credibility assessment. This also should include documentation of the planned and execution verification and validation, e.g., to cover these areas of the PBPK model development and evaluation: 1. Verification activities will ensure the correctness of implementation of model code and the accuracy of the underlying software and algorithms. Verification will be accomplished via test scripts, peer code reviews, built-in model sanity checks (e.g., PBPK mass-balance checks), etc. 2. Validation activities will ensure the accuracy of the overall model, the validity of model assumptions, and ability of the model to answer the specific questions of interest. Validation will be accomplished by comparison of model predictions with clinical data or other comparators. # Application Simulation ## Intended-use scenario-based applications: * DDI * Application Case Examples * Case-scenario of an industry-application PBPK bottom-up modeling approach used to evaluate the DDI potential of acalabrutinib and its active metabolite, with CYP3A inhibitors and inducers \[[149](/v12/references/references#149)]. * Model Template Development * Türk’s paper describes a comprehensive workflow of DDI module in PK-Sim and the Supplementary Materials to this manuscript were compiled as one comprehensive reference manual with transparent documentation of the model performance to support DDI investigations during drug development, labeling, and submission for regulatory approval of new drugs \[[145](/v12/references/references#145)]. * Special Populations / Organ Impairment * Pediatrics * Yun’s paper determined the appropriateness of the virtual individual creating algorithm in PK-Sim® in predicting PK parameters and their variability in children by comparing a model output, clearance, to observed data. Identified the critical system specific input parameters within a pediatric PBPK model structure for estimating exposure in children via a sensitivity analysis \[[147](/v12/references/references#147)]. * A brief overview of the development of pediatric physiologically based pharmacokinetic (PPBPK) models, the challenges of uncertain systems information, and finally performance verification considering recent regulatory guidance \[[138](/v12/references/references#138)]. * Pregnancy * These manuscripts provide overview of pregnancy model in PK-Sim and its major aspect of the model and physiology changes \[[132](/v12/references/references#132)] * Organ Impairment * Reviews * PBPK predictions can help determine the need and timing of organ impairment study. It may be suitable for predicting the impact of RI on PK of drugs predominantly cleared by metabolism with varying contribution of renal clearance \[[136](/v12/references/references#136)]. * CKD * The renal diseases also affect drug metabolization by the liver. Tan et al. provides a comprehensive workflow used for investigation of pharmacokinetics on patients with CKD \[[144](/v12/references/references#144)]. * Liver * PBPK Modeling for prospective dose recommendations and efficacy/safety assessment in special populations (when consistent clinical data are lacking). Example for a PBPK model to predict the effect of moderate and severe hepatic impairment on the PK of alectinib to best inform clinical study design \[[141](/v12/references/references#141)]. * Virtual Bioequivalence (VBE) * Average bioequivalence studies have been required by the FDA and the EMA. These publications explore a workflow and discuss data requirements to run Virtual BE using PBPK \[[139](/v12/references/references#139)], \[[140](/v12/references/references#140)]. * Regulatory Review * This report reviews the use of PBPK in decision-making during regulatory review. The report also discusses the challenges encountered when PBPK modeling and simulation were used in these cases and recommends approaches to facilitating full utilization of this tool.It also summarize general schemes of PBPK simulation and propose procedures to obtain necessary data to construct PBPK models. In order to fully utilize PBPK in drug development and regulatory review, it is critical to adequately define mechanisms of drug disposition and understand general physiological perturbations related to diseases,age, and organ dysfunction \[[148](/v12/references/references#148)]. * This white Paper summarises the FDA's view how a framework for evidential criteria for PBPK models can be established. With that the FDA reached out to the scientific community to stimulate a discussion about this topic \[[137](/v12/references/references#137)]. * Overview on use of PBPK for submissions to the FDA. Discusses limitations and knowledge gaps in integration of PBPK to inform regulatory decision making, as well as the importance of scientific engagement with drug developers who intend to use this approach \[[135](/v12/references/references#135)]. ## Simulation (i.e. application) design / strategy considerations: * Population-level vs mean * This case study for Caffeine shows that individual pharmacokinetic profiles can be predicted more accurately by considering individual attributes and that personalized PBPK models could be a valuable tool for model informed precision dosing approaches in the future \[[134](/v12/references/references#134)]. * Workflow Review * This review of several case studies provides is for a better understanding of the absorption, distribution, metabolism and excretion (ADME) workflow of a drug candidate, and the applications to increase efficiency, reduce the need for animal studies, and perhaps to replace clinical trials. The regulatory acceptance and industrial practices around PBPK modeling and simulation is also discussed \[[150](/v12/references/references#150)]. * Hypothesis generation * The aim of this paper was to develop an analysis framework to investigate whether population modelling approach can be used to estimate PBPK model parameters from clinical PK data and establish the required criteria for such estimations \[[131](/v12/references/references#131)]. * Regulatory Confidence * It is a perspective case of workshop entitled “Application of Physiologically-based Pharmacokinetic (PBPK) Modeling to Support Dose Selection” was hosted on March 10, 2014 by the US Food and Drug Administration (FDA) at its White Oak Campus in Silver Spring, MD. The workshop endeavored to (i) assess the current state of knowledge in the application of PBPK in regulatory decision-making, and (ii) share and discuss best practices in the use of PBPK modeling to inform dose selection in specific patient populations \[[146](/v12/references/references#146)] * This white Paper summarises the FDA's view how a framework for evidential criteria for PBPK models can be established. With that the FDA reached out to the scientific community to stimulate a discussion about this topic \[[137](/v12/references/references#137)]. * Case-based strategies for different application scenarios * This work presents a systematic assessment of the current challenges to establishing confidence in PBPK models with respect to parameter estimation and model verification in each of the three major areas of PBPK application absorption prediction, exposure prediction in a target population, and DDI risk assessment during drug development \[[142](/v12/references/references#142)]. # Documentation While PBPK modelling is applied to inform decision making in the pharmaceutical industry to e.g. inform go/no-go decisions, formulation development, a dosing strategy in pediatrics or a DDI strategy one should keep in mind that PBPK modelling is a robust tool to support drug/chemical safety or toxicity risk assessment in general. Independent of whether PBPK modelling is used for internal decision making or for decisions by regulators, a minimum level of documentation is recommended to facilitate traceability and, later on, review by regulators. This minimum level of documentation should allow for establishing the link between data, data transformations and manipulation, final model/simulation code, and conclusions in order to facilitate traceability. The manuscript “Good practices in model-informed drug discovery and Development (MID3): Practice, Application and Documentation” \[[169](/v12/references/references#169)] provides an overview on different levels of documentation (memo, report), a suggestion for documentation of analysis plans and reports including high-level guidance for authors with respect to content and audience. Guidance on documentation of assumptions and assessment of assumptions during model development is also provided . A recent publication by Tan et al. focuses on PBPK model reporting for chemical risk assessment, expanding the already existing guidances for pharmaceutical applications by recommending additional elements that are relevant to environmental chemicals, providing a more general and harmonized framework for reporting of PBPK models \[[170](/v12/references/references#170)]. ## Documentation during the conduct of an analysis It is recommended to create a summary of the parameter identification steps describing all relevant steps and tested models leading to the current best model. It is recommended to capture the following information: * Analysis dataset used for parameter identification * Simulations included * Rationale for the model / hypothesis tested * Outcome/evaluation of the parameter identification step * Parameters used in final model Most of the commercial PBPK software offer a built-in tracking of parameter identification steps such as e.g. the journal function in OSP. ## Reporting (including analysis plans) of PBPK analysis FDA and EMA have both issued guidance documents for the industry on reporting of PBPK analysis outlining the recommended format and content of a report for regulatory submissions \[[125](/v12/references/references#125)], \[[126](/v12/references/references#126)]. The EMA guidance clarifies their expectation on qualifying a PBPK platform for the intended use. A more detailed overview on sections to be included in such a report and guidance on expected content in each section is provided in Table 4 of a review on “Physiologically Based Pharmacokinetic Model Qualification and Reporting Procedures for Regulatory Submissions: A Consortium Perspective” by \[[128](/v12/references/references#128)]. The outlined sections are in line with the MID3 recommendations and the FDA guideline. Supplements to this publication include a template for analysis plans and reports. A more recent publication \[[170](/v12/references/references#170)] focuses on PBPK model reporting for chemical risk assessment applications. It expands the existing guidances \[[125](/v12/references/references#125)], \[[126](/v12/references/references#126)], \[[128](/v12/references/references#128)] for pharmaceutical applications to support the assessment of the safety of environmental chemicals. The publication provides very detailed expectations towards the content of each section which go beyond the level of detail as provided by the existing guidelines. While Tan et al. address underlying modelling assumptions as part of the method section, Marshall et al. and Shebley et al. suggest a stand-alone section including documentation of assessing the impact of uncertainties in the assumptions taken. # Modeling Concepts # PBPK Modeling - Systems Biology Systems biology is a multidisciplinary field of research. It is about understanding and investigating biology from a systems perspective. That is to say, the focus is not on isolated parts or processes, but on their interaction by which a certain behavior is generated or a certain task is fulfilled. In modern science and engineering, systems are often studied using mathematical models. Mathematical models can be used to aggregate and integrate existing knowledge with the aim of systematically analysing system behaviour, testing and generating hypotheses, and planning the next experimental steps. The idea of using mathematical models to investigate biology is not new. What is relatively new is the increasing recognition and appreciation that mathematical models can be an efficient way of learning and can form the basis for decision-making. Molecular complexity forms the basis of life, and it is clear that system boundaries and certain levels of detail within a model may be limited. While experiments are and will remain an essential part of biological (and systems biological) research, in line with many "systems biologists", we consider mathematical models as the core discipline of systems biology. Consequently, in this manual, if we speak simply of models we mean mathematical models and we will indicate if another form of model is used. The content of this manual is naturally selected and biased. Systems biology includes many levels of biological diversity, but we will focus on organisms and topics of broader relevance in pharmaceutical research and development, i.e., systems pharmacology. However, many facets of the software can be used beyond systems pharmacology. While the very early phases of drug development do generally not involve work on whole organisms (animals or humans), the late preclinical phase includes animal experimentation mainly in mammals such as mice, rats, dogs, or monkeys before entering the clinical phase, where the focus is on human participant research as outlined below. Various modeling approaches have been developed to support investigations on different scales [39](/v12/references/references#39). As outlined above, we will focus on systems pharmacology, which can be viewed as a mechanistic approach to the study of pharmacodynamics and pharmacokinetics. ![Phases, costs, and biological systems used in drug development](/files/RG4CAhW4pqqv08tLfNxv) # PK and PD Modeling Pharmacokinetics (PK) may be defined as what the body does to the drug, as opposed to pharmacodynamics (PD), which may be defined as what the drug does to the body \[[4](/v12/references/references#4)]. The site of action of a pharmacological substance might be restricted to specific tissues or cells, which is why a quantitative estimate of the amount of administered substance that is available at the site of action is required. This question is the subject of pharmacokinetics, and different modeling techniques are well-established in pharmaceutical research to support its investigation. So far, the most widely used approach is to establish descriptive and comparatively simple compartmental PK models that can be well identified based on available data. Often these models are applied to population PK data using nonlinear mixed-effect techniques (NLME), e.g., to quantify sources of population variability or covariate effects. Besides PK, such models may also include a description of a compound's effects (PD), for example, in the form of a simple hyperbolic or sigmoid concentration-effect relation (Michaelis-Menten, Hill, or Emax type). In classical pharmacokinetic modeling, the aim is to fit a comparatively simple model to experimental data in order to determine pharmacokinetic parameters from the fitted concentration-time course. These parameters are used to characterize and quantify the behavior of the investigated substance in general or in a certain clinical trial and, potentially, to extrapolate to situations that have not already been investigated. In contrast to the rather phenomenological consideration of drug PK in compartmental models, physiologically–based pharmacokinetic (PBPK) models aim for a detailed representation of physiological processes, as will be summarized in the following. Consequently, PBPK modeling is based on the mathematical description of physical and physiological processes, and in the framework of PBPK modeling, a genuine simulation of the pharmacokinetic behavior using this description is performed. Also, the PD can be represented mechanically, as discussed in [Modeling Concepts - PD and Reaction Network Modeling](/v12/mechanistic-modeling-of-pharmacokinetics-and-dynamics/modeling-concepts/modeling-concepts-pd-and-reaction-network-modeling). A good starting point for further reading can be found in \[[65](/v12/references/references#65)]. ![Structure of compartmental PK model (A) and PBPK model (B)](/files/OACrkdYoJmLQnt1bvlkJ) # Principles of PBPK Modeling ## Introduction to PBPK Modeling Physiologically-based pharmacokinetic (PBPK) modeling is a mechanistic approach to describe the pharmacokinetics of a substance based on substance-specific properties and mammalian physiology, for which a substantial amount of prior biological information is used for model building, \[[92](/v12/references/references#92)], \[[93](/v12/references/references#93)], \[[95](/v12/references/references#95)], \[[96](/v12/references/references#96)], \[[97](/v12/references/references#97)], \[[14](/v12/references/references#14)], \[[22](/v12/references/references#22)], \[[69](/v12/references/references#69)], [\[116\]](/v12/references/references#116) - \[[120\]](/v12/references/references#120). The general idea, introduced as early as 1924 \[[31](/v12/references/references#31)], is to divide the body into physiologically relevant compartments, mainly the relevant organs, and to set up a mass balance equation for each compartment describing the fate of the substance within that compartment \[[76](/v12/references/references#76)]. In PK-Sim®, a physiological framework model is provided where the mammalian body is divided into containers representing relevant organs or tissues and arterial and venous blood pools connecting the different organs through the blood flow. Organs are further subdivided into several subcompartments that describe essentially the vascular space, divided into plasma and (red) blood cells and the avascular space, divided into interstitial and cellular space. Such a model framework corresponds to a detailed compartmental model and provides the structural basis to describe the behavior of a substance. For the simulation of the whole body, all mass balance equations are combined in a system of interdependent differential equations. In the simplest version of this system, all organs are connected in parallel between the arterial and venous blood pools, such that the blood flows from arteries to veins, except in the lung, where the circulation is closed by a blood flow in the opposite direction. When carrying out a simulation, this system of time-dependent differential equations is solved numerically. The primary results of such PBPK simulations are concentration-time courses of the compound in the various compartments explicitly described in the equations. This means that besides the plasma concentration, at least one concentration curve for each organ is included in the output. Of course, derived PK parameters such as the area under the curve (AUC) or the maximum concentration (Cmax) can be calculated based on the primary output. PBPK can also be well understood within ADME logic, which is further detailed below. ## (L)ADME logic and routes of administration The pharmacokinetics of a substance can be understood by considering its (liberation), absorption, distribution, metabolism, and excretion (ADME). While intravenously administered substances are directly available in the systemic circulation for distribution, substances administered, e.g., orally, subcutaneously, or via inhalation, must be absorbed first. Also, in some cases, the substance might not be directly available for absorption, but needs to be liberated first, in case an extended LADME scheme is relevant. ### Liberation Depending on the formulation of a substance, it might not be directly available for absorption processes. Certain formulations liberate the substance in a more or less controlled fashion, and these processes can be included in PBPK models. Further details on modeling liberation in PK-Sim® are described in [PK-Sim® - Formulations](/v12/working-with-pk-sim/pk-sim-documentation/pk-sim-formulations). ### Absorption Substances not administered intravenously generally must be absorbed before being available in the systemic circulation. The most common route of administration for which absorption is a critical issue is oral (per os, PO) administration. Factors such as gastric emptying and intestinal transit time, stability and solubility of a substance or formulation, as well as the permeability across the intestinal wall based on passive and active transport processes, are essential for the fraction of a substance absorbed into the systemic circulation. Bioavailability is further determined by potential first-pass metabolism as described below. Historically, a plug-flow-with-dispersion model was used in PK-Sim® \[[93](/v12/references/references#93)]. From version 5.0 on, a compartmental gastrointestinal model is used, which is further detailed and discussed in \[[79](/v12/references/references#79)] and \[[80](/v12/references/references#80)]. ### Distribution After reaching systemic circulation, the compound may distribute into tissues and organs, decreasing the plasma concentration. The (apparent) volume of distribution is an important PK descriptor, theoretically defined as the volume in which the total amount of drug would need to be uniformly distributed to produce the given plasma concentration of a compound. However, the physiological processes that determine this volume may be complex. The basic passive processes, which determine the behavior of a substance in an organ, are mass transport via the blood flow, permeation from vascular space into organ tissue, and partitioning between blood plasma and organ tissue. The level of detail used for the description of these processes in a PBPK model can vary significantly. For the description of the passive physical processes involved in partitioning into the organs, usually two concepts are distinguished: blood flow-limited and permeation-limited partitioning. In the first case, all organs are assumed to be well-stirred compartments that equilibrate instantaneously with the plasma, and the time constant for the distribution of a substance into the peripheral organ is determined only by the blood flow rates. Alternatively, in models with permeation limitation, a permeation barrier is assumed between blood and organ tissue, resulting in a permeability dependence of the distribution and the corresponding time constants. Other important parameters determining the distribution behavior are the partition coefficients between the organ tissues and the blood plasma. These partition coefficients are given by the tissue to plasma concentration ratio under steady state conditions. Besides the passive processes described above, active transport processes or binding to proteins, including the target, can strongly influence the distribution behavior. The relative contribution of different processes to distribution also depends on the type of the molecule. The blood endothelium in the different organs often does not constitute a major distribution hurdle for small molecules. An exception is the significant blood-brain barrier. For larger molecules such as biologics, endothelial permeation can significantly impact the PK, and additional processes, such as lymph flow, are important for recirculation. Further details and options for modeling distribution in PK-Sim® are described in ["Partition coefficient calculation methods”](/v12/working-with-pk-sim/pk-sim-documentation/pk-sim-compounds-definition-and-work-flow#definition-of-new-compounds-in-pk--sim). ### Metabolism Most substances are metabolized by enzymes in the organism. Often, two distinct phases are distinguished: Phase I enzymes catalyze modifications that generally add functional groups to non-polar molecules; Phase II enzymes can then conjugate soluble molecules to these groups to allow better elimination via the kidney or the gall bladder. The products of such biotransformation steps are referred to as metabolites. If they are not active, they are often not further considered. However, metabolites can also constitute the pharmacologically active form of the substance or be responsible for side effects. Generally, the liver is considered the most relevant organ for biotransformation. However, most metabolizing enzymes are also expressed in various other organs, even though often to a lower extent. Nevertheless, extrahepatic metabolism can be very important. Mucosal clearance in the intestinal wall is just one prominent example. Together with first-pass clearance in the liver, this process also influences the bioavailability of a substance \[[77](/v12/references/references#77)]. Metabolism is generally an active and substance-specific process. While the enzyme equipment is a property of the organism, it has to be considered for each substance for which enzymes are relevant. Further details on modeling metabolism in PK-Sim® are described in the section [ADME Properties](/v12/working-with-pk-sim/pk-sim-documentation/pk-sim-compounds-definition-and-work-flow#adme-properties-tab). ### Excretion/Elimination Compounds and their metabolites are generally removed from the body via excretion or elimination processes. The two most prominent routes of excretion are via the kidney into urine and via biliary excretion into the intestine and further into the feces. During the latter process, reabsorption can lead to entero-hepatic circulation of a substance. While biliary secretion is generally mediated via active transport, urinary secretion can be passive (glomerular filtration) or also due to active transport (tubular secretion). Other special routes of elimination can include exhalation via the lungs. Just like the metabolization processes, the transporter "equipment" is a property of each individual organism. For each substance, it has to be considered which transporters are relevant and whether or not the substance is subject to glomerular filtration. Further details on modeling excretion and elimination in PK-Sim® are described in [ADME Properties](/v12/working-with-pk-sim/pk-sim-documentation/pk-sim-compounds-definition-and-work-flow#adme-properties-tab). ## PBPK model parameterization Due to its physiological basis, most parameters in a PBPK model are independent of substance knowledge or PK measurements. For example, information on blood flow rates, compartment volumes, or composition, e.g., in terms of volume fractions of water, proteins, and lipids, can be implemented independently of the substance. For establishing PBPK models to describe virtual humans, the physiological knowledge is not restricted to average individuals. For many parameters, their distribution within different populations is known in an age-dependent or subject-specific manner, allowing population PK predictions or extrapolations rather than fitting to data for interpolation. PBPK models can also be established for different animal species. With an established animal PBPK model at hand, for example, the physiological parameters can be substituted to make a first prediction for humans. The physiological correspondence of parameters enables both a good interpretation of results as well as a translation to new scenarios of application. Consequently, PBPK models are well-established in environmental toxicology and risk assessment fields and are becoming increasingly popular in pharmaceutical research. In addition, PBPK models automatically provide exposure estimates at the site of action and, therefore, provide a natural basis to build multiscale PK/PD models and thereby provide a good platform for knowledge integration along the pharmaceutical research and development process \[[85](/v12/references/references#85)]. Besides this general information on mammalian physiology, PBPK models use generic distribution models. Using these models, only a few basic physicochemical parameters of the substance, such as molecular weight, lipophilicity, and protein binding, can be used to determine relevant passive processes, such as permeabilities across membranes and partition coefficients between compartments, to describe the PK behavior. Additional parameters are required for the representation of active processes, such as transport or enzyme-catalyzed metabolization. # Expression Data for PBPK Modeling The most prominent examples of proteins that affect PK are enzymes that catalyze the metabolism of drugs or transporters that can heavily influence drug absorption or distribution. Proteins can also include those which a drug binds to, either by design (drug-target interaction) or as an off-target interaction or side-effect. Such binding can also influence the distribution, as well as the metabolism and excretion of the drug. In physiologically-based PK modeling approaches, it is desirable to mechanistically reflect such relevant drug-protein interactions. In some cases, the addition of one specific protein into the most relevant organ is sufficient to describe a process, e.g., cytochrome P450 3A4-mediated metabolization in the liver. In other cases, it may be necessary to consider protein levels in more than one organ. The integration of a protein expression database with PK-Sim makes it easy to assign parameter values for the involved proteins to account for differential protein expression in various organs and assign them to virtual individuals. As such, the user describes the absolute amount of protein in one reference organ, and through the use of relative expressions as generated with the protein database, the protein concentrations are fixed for all organs where the protein is present. Details on how to use the protein expression database are described in [PK-Sim® - Expression Data](/v12/working-with-pk-sim/pk-sim-documentation/pk-sim-expression-profile). See \[[46](/v12/references/references#46)] for an example that demonstrates how taking into account protein expression leads to an increase in PBPK model quality. Alternatively, the user can assign one set of kinetic parameters characterizing the drug-protein interaction (e.g., kcat and Km, or kon and koff) and use this in all organs. # Modeling of Proteins Therapeutic proteins are an increasingly important class of drugs. Particularly, monoclonal antibodies are used for different indications including cancer, inflammatory and autoimmune diseases \[[88](/v12/references/references#88)]. These engineered antibody fragments with tailored pharmacokinetic properties have the potential to be used as diagnostic and therapeutic agents \[[34](/v12/references/references#34)]. PK-Sim® offers a model specifically designed to describe the pharmacokinetics of proteins and other macromolecules [\[114\]](/v12/references/references#114). The pharmacokinetics of protein therapeutics are governed by a number of unspecific and specific processes, which have to be incorporated to describe the pharmacokinetics of protein therapeutics. This includes \[[42](/v12/references/references#42)]: * Exchange across the vascular endothelium between plasma and the interstitial space by convection and diffusion. * Return of the drug from the interstitial space of the organs to the circulation by lymph flow. * Degradation and protection from degradation by neonatal Fc receptor (FcRn) in cellular endosomes. * Target-mediated disposition and clearance. This model was developed by extending the standard model for small molecules by a description of the transcapillary drug exchange, lymph flows and endosomal space including drug degradation and protection from degradation by the FcRn receptor. Within this model, the transcapillary exchange of the drug is described by the two-pore formalism \[[58](/v12/references/references#58)], \[[57](/v12/references/references#57)], \[[3](/v12/references/references#3)]. According to this theory, the barrier between plasma and interstitial space is described as a membrane consisting of two types of pores: a few large and many small ones. Macromolecules can pass through these pores by convection as well as diffusion. To describe these processes, the endothelial permeabilities and osmotic reflection coefficients of the drug for the different organs are calculated within PK-Sim® from the Stokes radius of the drug and endothelial properties like pore radii and hydraulic conductivity \[[58](/v12/references/references#58)]. The FcRn sub-model is based on the model published by Garg and Balthasar \[[26](/v12/references/references#26)]. The fraction of the drug that is bound to FcRn within the endosomal space is recycled to the plasma and the interstitial space, whereas the fraction not bound to FcRn is cleared from the endosomal space. In PK-Sim®, endosomes represent the endosome in the vascular endothelium only and serve as a compartment for the protein. Endogenous IgG is also represented, which competes with the drug for the FcRn receptor. The clearance of the drug thus depends on its affinity to the FcRn receptor, the endosomal concentration of endogenous IgG, and the endosomal concentration of the FcRn receptor. The main difference to the model published by Garg and Balthasar \[[26](/v12/references/references#26)] is that in the PK-Sim® model, there is binding to the FcRn receptor, which is explicitly represented, and, thus, different affinities to the FcRn receptor can be specified for the drug and the endogenous IgG. Nonspecific binding or specific binding of the therapeutic protein to its target can be added within PK-Sim®. Specific binding within a tumor or a detailed description of target-mediated clearance by receptor internalization can be added within MoBi® based on a PK-Sim® protein. # PD and Reaction Network Modeling Pharmacodynamics (PD) describes the interactions of drugs with the organisms. This includes binding of drugs to their targets (which may also be relevant for understanding the PK) and resulting direct or indirect effects. Pharmacodynamics can also relate drug concentration profiles (PK) to clinical endpoints, which usually requires consideration of disease progression. Various modeling approaches are used to analyze PD or disease progression, either alone or in combination with PK. Simple models use a sigmoidal function to relate a concentration to its effects (e.g., Hill, IC50, Emax-shape). Here, the maximum effect and the concentration that corresponds to half the maximum effect are typical curve characteristics. Such approaches can be combined with advanced statistical methods, as the effect of a drug is rarely fully deterministic. Inter-individual or inter-occasion differences can be investigated and quantified in such a way, see [Modeling Concepts - PK and PD Modeling](/v12/mechanistic-modeling-of-pharmacokinetics-and-dynamics/modeling-concepts/modeling-concepts-pk-and-pd-modeling). Transferring or translating such models to new application scenarios is often not straightforward. A typical question to answer would be how the curve characteristics are expected to change in the new situation. However, if the model explicitly considers the crucial physiologic and mechanistic aspects, and it is known from independent experiments how these change in certain scenarios, a translation and prediction can become feasible. The level of mechanistic detail needed depends on the particular problem. In certain cases, the desired detail might include sophisticated reaction networks. Sometimes, these are sufficient on their own to understand relevant PD behavior. Detailed pathway modeling is also a major activity in systems biology in academia. Many excellent reviews are devoted to this topic, which will not be further detailed here. In other cases or for other questions, the PK/PD interaction is important to consider. Here, PBPK models offer an intuitive framework for coupling PK with simple or mechanistic PD models. See \[[18](/v12/references/references#18)] for a recent example. # Modules, Philosophy, and Building Blocks ## Introduction The Open Systems Pharmacology Suite (OSPS) contains different software tools and has been designed using a modular concept to allow efficient multi-scale modeling and simulation workflows. The ecosystem of the different software tools and their interactions is explained in the [Software Ecosystem](#software-ecosystem) section. The central software tools PK-Sim® and MoBi® make use of the building blocks concept as introduced in [PK-Sim® and its building blocks](#pk-sim) and [MoBi® and its building blocks](#mobi). PK-Sim® is based on a whole-body physiologically-based modeling concept, while the focus of MoBi® lies on modeling complex signaling pathways and extending the standard PBPK framework. The different physiological scales that are covered by the different tools are illustrated below. ![Multiscale modeling and simulation (taken from \[18\])](/files/exp0CJ14BYCOKx8OxOin) ## PK-Sim® PK-Sim® is a comprehensive software tool for whole-body physiologically based pharmacokinetic (PBPK) modeling \[[92](/v12/references/references#92)]. It enables rapid access to all relevant anatomical and physiological parameters for humans and common laboratory animals (mouse, rat, minipig, dog, monkey, and rabbit) contained in the integrated database. Users can access different PBPK calculation methods for fast and efficient model building and parameterization. Relevant generic passive processes, such as distribution through blood flows as well as specific active processes, such as metabolization by a particular enzyme, are automatically taken into account by PK-Sim®. Like most PBPK modeling tools, PK-Sim® is designed for use by non-modeling experts and only allows for minor structural model modifications. Unlike most PBPK modeling tools, though, PK-Sim® offers different model structures to choose from, e.g., to account for important differences between small and large molecules (see [Model settings](/v12/working-with-pk-sim/pk-sim-documentation/pk-sim-simulations#model-settings)). More importantly, PK-Sim® is accompanied by the expert modeling software tool MoBi®, allowing full access and transparency to all model details, including the option for extensive model modifications and extensions. This way, customized systems pharmacology models may be set up to deal with the challenges of modern drug research and development. PK-Sim® applies the building blocks concept, separating information used for model building into groups: Individuals, Populations, Compounds, Formulations, Administration Protocols, Events, Observers, and Observed Data. The different building blocks are described in detail in “Working with PK-Sim®”. Building blocks from these groups are combined to generate a model. The advantage of building blocks is that they can be reused and combined to create different models. For example, after establishing a drug model after single-dose intravenous administration to an animal species, substitute the individual with a suitably parameterized virtual human population and obtain a first-in-man simulation model. Further substitute the formulation to get a controlled-release per oral simulation model, substitute the protocol to obtain a multiple dose simulation model, or replace the compound to obtain a simulation model for another drug. PK-Sim® will be described in detail in [Working with PK-Sim®](/v12/working-with-pk-sim/pk-sim-documentation/pk-sim-quick-guide). ## MoBi® MoBi® is a systems biology software tool for multiscale physiological modeling and simulation. Within the restrictions of ordinary differential equations, almost any kind of (biological) model can be imported or set up from scratch. Examples include biochemical reaction networks, compartmental disease progression models, or PBPK models. However, de novo development of a PBPK model, for example, is very cumbersome, such that the preferred procedure is to import them from PK-Sim®. Importantly, MoBi® also allows for the combination of the described examples and thereby is a very powerful tool for modeling and simulation of multi-scale physiological systems covering molecular details and whole-body architecture. De novo model establishment and simulation are supported by graphical tools and building blocks to support expert users. MoBi® uses building blocks that are grouped into Molecules, Reactions, Spatial Structures, Passive Transports, Observers, Events, Molecule Start Values, Parameter Start Values, and Observed Data. The different building blocks are described in detail in [Working with MoBi®](/v12/working-with-mobi/mobi-documentation/first-steps). Building blocks out of the above-mentioned groups can be combined to generate models. The advantage of building blocks is that they can be reused. Examples: * a different set of starting values may define a new scenario, situation, or individual. * refine a Reaction(s) network and update it in all tissues where it should be considered. All building blocks are further organized into **modules**. The modules are either full-scale PBPK models imported from PK-Sim, or extensions to the default PBPK structure, effect models, or any model customization. The modules are combined into **simulations**, allowing for flexible and efficient model development and simulation. MoBi® will be described in detail in [Working with MoBi®](/v12/working-with-mobi/mobi-documentation/first-steps). ## Software Ecosystem The software ecosystem is outlined in the figure below. Apart from the two central, graphical user interface (GUI)- based software tools PK-Sim® and MoBi®, the software platform is supported by an ecosystem of various R packages, including a qualification framework, validation and automation tools, and specialized workflows for modeling and simulation. ![The software ecosystem](https://raw.githubusercontent.com/Open-Systems-Pharmacology/Suite/refs/heads/develop/OSP_software_landscape.svg) ### Qualification framework The qualification framework enables automated validation of various scenarios (use cases) supported by the OSP platform. This technical framework is used, for example, to release a new version of the OSP Suite in full confidence by automatically verifying that an ever-growing list of scenarios is performing as expected. The qualification framework will be described in detail in [Qualification](/v12/shared-tools-and-example-workflows/qualification). ### Validation and automation tools Validation and automation tools include, for example: * **Installation Validator**: enables "1-Click" validation of the OSP Suite installation on a target computer. The validation is performed by execution of the predefined set of simulation scenarios and comparison of the simulated results with the (validated) reference values. * **Command Line Interface** (*CLI*): allows batch processing of multiple projects in PK-Sim and is described in [Command Line Interface - CLI](/v12/working-with-pk-sim/pk-sim-documentation/pk-sim-command-line-interface). ### R-packages The OSP software suite provides a set of packages for the R computing environment that allow scripted workflows with the models developed in PK-Sim® and MoBi®. * [ospsuite](https://github.com/Open-Systems-Pharmacology/OSPSuite-R) package provides the functionality of loading, manipulating, and simulating the simulations created in PK-Sim® and MoBi®. It also offers extended workflows such as parameter sensitivity or PK-parameter calculation. The package is described in detail in [R documentation](/v12/working-with-r/introduction-ospsuite-r). * [tlf](https://github.com/Open-Systems-Pharmacology/TLF-Library) package offers a set of functions and methods for creating standardized reporting **T**ables, **L**istings, and **F**igures. * [ospsuite.reportingengine](https://github.com/Open-Systems-Pharmacology/OSPSuite.ReportingEngine) for automated generating of model reports. * [ospsuite.parameteridentification](https://github.com/Open-Systems-Pharmacology/OSPSuite.ParameterIdentification) provides the functionality of performing parameter identification (i.e., fitting the model to observed data) with simulations. The package is currently under development and everyone is encouraged to contribute. {% hint style="info" %} OSP Qualification Framework and R packages are not included into the main OSP Suite setup and must be installed separately. Installation instructions are provided in the documentation of the tools or on the GitHub download site. {% endhint %} ### OSP Model exchange format Models created in PK-Sim® or MoBi® can be exported in *PK Modeling Language* (\***.pkml**) format and shared between the OSP tools. Internally, the PKML file format is an XML format with a predefined structure. ### Import and Export Apart from the communication and exchange via R, PK-Sim® and MoBi® have import and export functions for MS Excel®, CSV, and NONMEM® that allow for the import of experimental data or the export of simulation results, for example. MoBi® has SBML import functionalities. PK-Sim can also import and export *project snapshots* in [JSON format](https://en.wikipedia.org/wiki/JSON) (s. [Exporting Project to Snapshot](/v12/working-with-pk-sim/pk-sim-documentation/importing-exporting-project-data-models#exporting-project-to-snapshot--loading-project-from-snapshot) for details). # Getting Started ## Software and Hardware Requirements | OS | Windows 10®, Windows 11®, Windows Server 2019®, Windows Server 2022®, Windows Server 2025® | | ---------- | ------------------------------------------------------------------------------------------ | | Processor | minimum 1 GHz (the faster, the better) | | Memory | 2 GB RAM, 4+ GB recommended | | Disk space | minimum 2 GB | | | **Optional software** | | R® | version 4.1 or higher - 64bit | The information provided above refers to the core components of the Open Systems Pharmacology Suite, including PK-Sim® MoBi®. Both PK-Sim® and MoBi® can be installed as stand-alone software packages to reduce the disk space required. {% hint style="warning" %} The Open Systems Pharmacology Suite includes interfaces to MS Excel® and R. These are separate programs that are not available within the Open Systems Pharmacology Suite. You need to have these programs installed to use their interfaces! {% endhint %} ### Trademark Information Excel® is a registered trademark of Microsoft Inc., Redmond, USA; R is a product of the R Foundation for Statistical Computing, Vienna, Austria. ## Installation and Update ### Core Components {% hint style="warning" %} To correctly install the software, administrator rights are necessary. If you do not have these rights, your IT administrator should carry out the installation. {% endhint %} {% hint style="info" %} The modular structure of the Open Systems Pharmacology Suite is explained in [Modules, Philosophy, and Building Blocks](/v12/open-systems-pharmacology-suite/modules-philsophy-building-blocks). Both PK-Sim® and MoBi® can be installed as stand-alone applications. However, to obtain the full modeling and simulation capabilities, we recommend that both programs are installed. {% endhint %} To install the Open Systems Pharmacology Suite core components: 1. Download installation packages from . 2. Start the **OSPSuite-Full.X.Y.Z.exe**\* (where X.Y.Z is a program version, e.g. 12.0.397) from the menu Start -> Run or from Windows Explorer. 3. Follow the instructions of the installation program. In most cases, the installation should be carried out with the default settings. 4. In most cases, you will have to restart your computer following installation. 5. Download PK-Sim® [gene expression databases](https://github.com/Open-Systems-Pharmacology/Gene-Expression-Databases/releases) and copy them to a folder accessible for all users. 6. Configure PK-Sim® gene expression databases (for details, see [PK-Sim® - Options](/v12/working-with-pk-sim/pk-sim-documentation/pk-sim-options)). ### (Re-)Qualification Framework Optional OSP Suite components which are only required for the [creation of qualification reports](https://docs.open-systems-pharmacology.org/shared-tools-and-example-workflows/qualification). Installation instructions are provided [here](https://docs.open-systems-pharmacology.org/shared-tools-and-example-workflows/qualification#tools). ### Third Party Tools In addition to the core components of the Open Systems Pharmacology Suite, including PK-Sim® MoBi®, interfaces are available for MS Excel®, Matlab®, and R. For purchasing and installation options, please contact the suppliers indicated in the section “Trademark information.” ## Help: Contact, Discussion Forum, Bug Reporting, ... Additional information on the software is available on . For support, bug reports, etc., please contact . # PK-Sim Documentation # Quick Guide Here, only the basic steps needed to work with a PBPK simulation in PK-Sim® are briefly described (creation of a model, comparison of simulation data to observed data, and refinement of the model): ![Image](/files/Zek2TDFIY5ENkyhxSm8S) ![Image](/files/9QMDAjeI8APqTNnN84kN) ![Image](/files/V1ZNfr7NZoACDc7cz9bN) ![Image](/files/JwrvX0A0OUXeGBBznDSm) ![Image](/files/1g8LNfg02SubHg4LSxx7) ![Image](/files/nuBTHXpfDr0JxsfEi6OC) # Options PK-Sim® can be customized using several options. To do this, click on the **Options** Button within the **Utilities** Ribbon Tab. ## **General** Tab ### Numerical Properties * **Allows scientific notation**: You can specify if parameter values and results are displayed in scientific notation and if they are very small or large. * **Decimal place**: You can specify the number of decimal places displayed for parameter values and results. * **Absolute tolerance** and **Relative tolerance**: You can specify the absolute and relative tolerance to control the error of the ODE solver. Changes will only affect simulations that are created after changing values. * **Maximum number of processors to use** for tasks that can be executed in parallel (population simulations, parameter identification, parallel execution of simulations). * **Number of bins**: number of bins to display in histograms of populations/population simulations for parameter distribution. {% hint style="warning" %} Setting tolerances higher than the default values (absolute tolerance: 1.0E-10; relative tolerance: 1.0E-5) may reduce simulation time but cause convergence errors. {% endhint %} ### Look and Feel * **Active skin**: The program's graphical appearance can be changed by changing the skin in the Skins group next to the Options icon. * **Number of recent file items shown**: Changes the number of recent documents displayed within the File Tab. The program needs to be restarted for the changes to take effect. * **Preferred view layout**: Choose from either tabbed or accordion view, e.g., the Compound window. * **Restore opened view when loading project**: Open tabs (e.g., particular simulations, individuals, or compounds) are saved upon saving and restored when re-opening the project. Warning—this may significantly impact a project's loading time! * **Show software update notification if available**: When enabled and connected to the internet, a check for new versions of PK-Sim® is done automatically. ### Defaults * **Species** and **Population**: Changes the default species and default population used for the creation of a new individual or population. * **Parameter layout**: Changes the default parameter layout used for parameters shown within the Anatomy & Physiology tab of an individual and the Parameters tab of a simulation. * **Lipophilicity**, **Fraction unbound,** and **Solubility**: You can specify the defaults for the description used for the Experiment input box when a new compound is created. * **Population analysis**: After the first simulation run, an analysis window opens automatically. This option sets the default type of this first analysis ('Time Profile', 'Box Whisker', ...). * **Chart y scale**: Default scaling (lin or log) of the y axis in new time-profile charts. ### Icon Sizes You can change the size of the icons displayed within the **Tree view**, the **Tabs,** and the **Context menu** ### Template Database * **Template database path:** The path to the template database. You can create a new template database by clicking on * **Load metabolites when loading compound:** Choose whether or not to load the metabolites of a compound when loading a (parent) compound. ### Colors * **Formula parameter**: Changes the background color for parameters that are calculated by a formula. * **Parameter changed**: Changes the background color for formula-calculated parameters that have been changed by the user. * **Chart background** and **Chart diagram background**: Changes the chart colors. For simulation charts, this is the default if no other color is specified in the Chart Editor of the Results Tab. * **Color group observed data from same folder when dropping to chart**: If enabled, when adding observed data sets to a chart via drag-and-drop from a folder (or multiple folders) within the "Observed Data" group, all data sets within one folder will get the same color. ## **Application** Tab * **MoBi Executable Path**: Path to the location of the MoBi.exe file Specify the path to a species-specific **Expression Database** you would like to use by clicking on the three dots in the **Expression Database** column in the row of the species you require. ![Linking a species-specific expression database to an individual.](/files/ks1L3rzfaoerYcPJ7A8M) The available expression databases can be downloaded from the [gene expression databases repository](https://github.com/Open-Systems-Pharmacology/Gene-Expression-Databases/releases). # Projects The organization of simulations is supported by PK-Sim® with a building block concept. Each project contains a **Building Blocks** panel that comprises one or several building blocks for individuals, populations, compounds, formulations, protocols, events and observed data. Simulations that are created with the building blocks and comparisons of simulations are organized in a separate panel. The user can create subfolders for organization of observed data, simulations and comparison. {% hint style="info" %} Only one project can be opened at a time in one PK-Sim® instance. If you wish to work on more than one project in parallel you may start separate instances of PK-Sim® for each individual project. If the identical project is already being accessed by yourself or by another user, PK-Sim® will warn you and open the project as read-only. You will still be able to use the project but won't be able to save your changes. {% endhint %} The following table gives an overview on how to manage projects using the **File** tab: | Function, Icon | Shortcut | Description | | ---------------------------------------------------------------------------------------------------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | |

Create a new project

| Ctrl+N | A new project is generated. The current project is closed. If you have not saved the current project yet, you will be asked if you want to do so. If you answer Yes, all data belonging to the current project are saved using the current file-name. If the project/file name is undefined, a dialog window will open for you to specify the project name. | |

Open an existing project

| Ctrl+O |

Select the \*.pksim5 file you want to open.
• Only one project can be opened at a time. If a project is already open, you are asked if the currently open project should be saved before closing.
• If you wish to work on more than one project in parallel, you may start separate instances of PK-Sim® for each individual project.

| |

Close the project

| | The project is closed. If you have not yet saved the current project, you are asked if you want to do so. If you answer Yes, all data belonging to the project are saved using the current file-name. If the project/ file name is undefined, a will open for you to specify the project name. A new project can then be created, subsequently. | |

Save the project

| Ctrl+S | You can save your project by either selecting Save or Save as. | |

Show or edit project description

| Ctrl+D | You can enter, show or change a description for the project. | |

Export project to snapshot

| |

Export current project to snapshot.
S. Exporting Project to Snapshot / Loading Project from Snapshot for details.

| |

Load project from snapshot

| |

Create a new project from snapshot.
S. Exporting Project to Snapshot / Loading Project from Snapshot for details.

| |

Select Journal

| |

Assign a working journal to the current project.
S. Shared Tools - Working Journal for details.

| |

About this application

| | An overview of the PK-Sim® version information is given. | |

Exit the application

| Alt+F4 | PK-Sim® is closed. If you have not yet saved the current project, you are asked if you want to do so. If you answer Yes, all data belonging to the project are saved using the current file-name. If the project name is undefined, a dialog window will open for you to specify the project name. | The visualization of a project is organized in different panels. Each panel can be hidden or be made visible by clicking on the respective icon in the **Views** Tab. The panels have the following meaning: | Panel, Icon | Description | | ------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | |

Building Blocks

|

Within this panel the building blocks Expression Profiles, Individuals, Populations, Compounds, Formulations, Administration Protocols, Events, Observers, and Observed Data are organized and can be accessed. Detailed information for each building block can be found in:
● PK-Sim® - Expression Profiles
● PK-Sim® - Creating Individuals
● PK-Sim® - Creating Populations
● PK-Sim®- Compounds: Definition and Work Flows
● PK-Sim® - Formulations
● PK-Sim® - Administration Protocols
● PK-Sim® - Events
● Shared Tools - Import and Edit of Observed Data.

| |

Simulations

|

In this panel all simulations of a project are managed. A detailed description on how simulations are set up and managed can be found in PK-Sim® - Simulations.
Besides simulations, this panel contains the following objects:
● Simulation comparisons (s. PK-Sim® - Simulations: Comparison charts for details)
● Parameter Identifications (s. Shared Tools - Parameter Identification for details)
● Sensitivity Analyses (s. Shared Tools - Sensitivity Analysis for details)

| |

History Manager

| Every user action performed within a given project work is documented within this panel. Features of the History Manager are described in [Shared Tools - History manager and history reporting](/v12/shared-tools-and-example-workflows/history-manager-history-reporting). | |

Comparison

|

Shows comparison results of 2 building blocks or 2 simulations.
S. Shared Tools - Comparison of Building Blocks for details.

| |

Working Journal

|

Shows the working journal of the current project.
S. Shared Tools - Working Journal for details.

| |

Working Journal Diagram

|

Shows the working journal of the current project.
S. Shared Tools - Working Journal for details.

| # Expression Profile ## Background: Active Processes in PK-SIM ### The role of proteins in PBPK modeling Small molecules frequently interact with proteins. Protein/compound interaction may influence all aspects of ADME to a varying extent. Metabolic and transport processes are of particular importance in this context. Most protein concentrations vary spatially as well as temporally. PK-Sim® allows the user to model proteins and compound/protein interactions. Active, protein-mediated processes involved in drug ADME generally occur simultaneously in various organs. However, a quantitative description of active processes is difficult due to the limited experimental accessibility of tissue-specific protein activity in vivo. PK-Sim® uses gene expression data as a surrogate for protein abundance to estimate in vivo activity of such enzymes or transporters that influence drug pharmacokinetics. This concept implies that protein availability and catalytic rate constants, which ultimately underlie enzyme and transporter activity, are decoupled. For more details, please see \[[46](/v12/references/references#46)]. In brief, the concept of using gene expression data as a proxy for protein abundance is based on the definition of the maximum velocity *Vmax* \[µmol/l/min]. According to the Michaelis-Menten equation, *Vmax* depends on both the total enzyme or transporter concentration E0 \[µmol/l] and the catalytic rate constant *kcat* \[1/min]: ![Equation 1](/files/Y1uzHs0XIN1SKSs6WmUr) Assuming that kcat is not influenced by in vivo factors, the tissue-specific maximum velocity *Vmax,organ* is defined as: ![Equation 2](/files/ppnhbZLVEA50m11d4UIV) ### Protein expression profile Following **Equation 2**, the effective rate of a protein-mediated process, be it metabolization, transport, or binding reaction, directly depends on the total amount of the protein in the respective compartment. The abundance of proteins in different organs in PK-Sim is calculated from **relative expression** values. For each organ, the relative expression defines the protein concentration in the whole organ as a fraction of a defined **reference concentration** value. ![Protein expression profile overview](/files/xl9ZOSuzeTTAAtwEetiQ) ### Reference concentration The **reference concentration** can be measured in vitro, allowing direct in vitro - in vivo extrapolation (IVIVE). The protein concentration in the organ with the **relative expression = 1** will equal that measured concentration. The concentrations in all other organs will be set relative to that value. If no in vitro protein abundance values are available for any organ, the reference concentration can be set to any arbitrary value (the default value is 1 µmol/L). While direct IVIVE will not be possible in this case, the model will still be able to account for the different contributions of the organs to the total process rate (e.g., metabolism of a compound) through the relative expressions. For example, the enzyme **CYP3A4** is mainly expressed in the liver of human adults, some in the gastrointestinal tract, and minor amounts in almost all other tissues. The concentration of CYP3A4 in the liver is 108 pmol/mg microsomal protein \[[63](/v12/references/references#63)]. The concentration of microsomal protein in the liver is 40 mg per g liver. Assuming a specific tissue density of 1 g/mL, the concentration of CYP3A4 in whole liver is 4.32 µmol/L. This number can be used as a reference concentration with a relative expression of 1 in the liver. The following table shows reference concentrations from a selection of CYP enzymes. The values were derived from measurements of human microsomal samples, see \[[63](/v12/references/references#63)]. Table: Reference concentration of CYP enzymes | Enzyme | pmol/mg human liver microsomes | µmol CYP/L liver tissue (Reference concentration) | | ------- | ------------------------------ | ------------------------------------------------- | | CYP1A2 | 45 | 1.8 | | CYP2A6 | 68 | 2.72 | | CYP2B6 | 39 | 1.56 | | CYP2C18 | <2.5 | <0.1 | | CYP2C19 | 19 | 0.76 | | CYP2C8 | 64 | 2.56 | | CYP2C9 | 96 | 3.84 | | CYP2D6 | 10 | 0.4 | | CYP2E1 | 49 | 1.96 | | CYP3A4 | 108 | 4.32 | | CYP3A5 | 1 | 0.04 | Special attention has to be paid when using ontogeny information together with the reference concentration. The reference concentration is subject to an age-dependent ontogeny, and the underlying implementation assumes that the reference concentration refers to an ontogeny factor of 1. For example, if it is known that for a 0.5-year-old individual, the ontogeny factor of a particular enzyme is 0.1, and the concentration of the enzyme in individuals of that age is 0.13 µmol/ L, the reference concentration (of an adult) is 1.3 µmol/L (that is 0.13/0.1). PK-Sim® supports different protein expression databases that must be configured in the PK-Sim® options, see [Options](/v12/working-with-pk-sim/pk-sim-documentation/pk-sim-options). As of August 2025, all models within the official [OSP PBPK Model Library](https://github.com/Open-Systems-Pharmacology/OSP-PBPK-Model-Library/releases/tag/v12.0) are built with the large-scale human gene-expression [database Version 2](https://github.com/Open-Systems-Pharmacology/Gene-Expression-Databases/releases/tag/v2.0.0). This database was compiled from publicly available sources that were downloaded, processed, stored and customized to be directly utilized in PBPK model building \[[63](/v12/references/references#63)]. The public databases that were imported are * whole genome expression arrays from ArrayExpress (ArrayExpress, 2010) * RT-PCR-derived gene expression estimates from literature \[[49](/v12/references/references#49)], \[[50](/v12/references/references#50)], \[[51](/v12/references/references#51)] * Expressed sequence tags (EST) from UniGene. The consolidated expression data was stored in a database with three sections: EST (UniGene), Array (ArrayExpress), and RT-PCR (literature cited above). A new [database Version 3](https://github.com/Open-Systems-Pharmacology/Gene-Expression-Databases/releases/tag/v3.0.1) containing expression profiles for various species, including humans, has been generated from the [Bgee](https://www.bgee.org/) database. It should be noted that the current databases only describe the spatial distribution of active processes in PBPK models. Temporal aspects such as circadian rhythms underlying chronogenetics are not included. If necessary, such effects may be considered in a corresponding MoBi® model. ### The cellular and tissue-specific location of active proteins Proteins involved in the metabolism or transport of compounds are located in different organ sub-compartments. While enzymes usually reside inside organ cells, transport proteins are located in membranes. Another important feature of biological cells that has to be considered is polarity. Organs containing epithelial cell membranes, like intestinal mucosa, liver (bile duct epithelium), and kidney (tubular epithelium), express different types of proteins on either side of the cell, whether basolateral or apical. The apical membrane is exposed to the luminal space, while the basolateral membrane faces the interstitial space of the tissue. The *relative expression* defines the concentration of the protein in the whole organ, i.e., the sum volume of the sub-compartments interstitial space, intracellular space, blood plasma and blood cells, and (for the large molecules model) the endosomal space. Within the organ, the protein can be distributed over the different sub-compartments, with the *effective concentration* in the compartment being calculated by PK-Sim such that the concentration in the whole organ ![Effective protein concentration](/files/bdcTVypuL9JTTNbr6y51) is ![Effective protein concentration](/files/JnPNYzOoU5xv6pkkC9AS) with ***RC*** being the reference concentration and ![RelExp\_Org](/files/bViGur9efdZodCJetQyZ) the relative expression in this organ. The following sections give an overview over the possible localizations and the equations used to calculate the effective concentrations in the different compartments for enzymes and transport proteins. ### Localizations and initial concentrations of enzymes ![Localization Enzymes](/files/w8gnlAr7BmpxkXNtEbjX) By default, an added enzyme is localized only in the intracellular space of the organs. The user can select additional compartments where the enzyme should be expressed and set the expression values. * **Plasma**: Enzymes floating in blood plasma. The specified relative expression will be added to the enzyme's expression in every organ's plasma compartment. * **Blood Cells**: Enzymes expressed in blood cells of all organs; the specified relative expression refers to blood cell volume. These enzymes can be located within blood cells or the cell membrane, facing the blood plasma. The relative distribution of the enzyme between the cellular space and the plasma membrane is defined by the parameters: * “*Fraction expressed in blood cells*” defines the amount of protein within the cell and acts on the educts located in the cell, * “*Fraction expressed in blood cell membrane*” is added to the expression in plasma and acts on the educts located in blood plasma. * **Vascular endothelium**: Enzymes expressed in arteries, veins, and capillaries. The relative expression refers to the volume of the vascular endothelium of the organ. Due to the specificity of implementation in PK-Sim, vascular endothelium is not explicitly modeled in the organs “Arterial Blood”, “Venous Blood”, and “Portal Vein”. * “*Fraction expressed in endosome*”: The enzyme is located in the endosomes of the vasculature. Please keep in mind that the endosomal compartment is not present in the model for small molecules. * “*Fraction expressed on plasma-side membrane of vascular endothelium*”: the enzyme is located in the membrane of endothelial cells facing blood plasma and acts on educts in plasma. The fraction of the relative expression is added to the expression in plasma. * “*Fraction expressed on tissue-side membrane of vascular endothelium*”: the enzyme is located in the membrane of endothelial cells facing the interstitial space and acts on educts in the interstitial space of the organ. The fraction of the relative expression is added to the expression in interstitial space. {% hint style="info" %} The relative expressions (and the fractions expressed at different sites) of the enzyme in the vascular system are equal for all organs. {% endhint %} * **Tissue**: The expression values for the organ tissue (excluding the vascular system) can be defined per organ and refer to the amount of the protein in whole organ (including plasma and blood cells). The “*Fraction expressed intracellular*” defines the concentration of the enzyme located intracellularly as fraction of total amount and acts on educts located intracellularly. The “*Fraction expressed interstitial*” defines the amount of the enzyme that is available in the interstitial space. Usually this refers to the enzymes located in the cellular membrane facing the interstitial space. NOTE: As per construction, it’s always `Fraction expressed interstitial = 1 - Fraction expressed intracellular` **Initial concentrations** of the enzymes in the different compartments within the model are combined from the relative expression values of organs having direct access to this compartment. The name “initial concentration” refers to the fact that these concentrations may change during simulation course e.g. through mechanism based inactivation. The concentration of the enzyme in the compartment ultimately defines the rate of the reaction catalyzed by this enzyme. {% hint style="info" %} The initial concentration value will be effectively calculated when the expression profile is linked to an individual e.g. when individual specific parameters such as volumes, hematocrit etc... are defined {% endhint %} To set a specific initial concentration value in a given compartment, simply overwrite the value in the expression profile for this specific compartment. This will effectively ensure that all individual using the expression profile will use the same initial concentration. {% hint style="warning" %} Do only overwrite initial concentration by hand if absolutely required. {% endhint %} * **BloodCells:** `RC * rel_exp_bc * f_exp_bc_cell` * *RC*: Reference concentration * *rel\_exp\_bc*: Relative expression in blood cells * *f\_exp\_bc\_cell*: Fraction expressed in blood cells * **Plasma (ArterialBlood, VenousBlood, PortalVein):** Combination of the expression in plasma and in blood cells in the membrane facing plasma. `RC * (rel_exp_pls + rel_exp_bc * f_exp_bc_membrane * HCT / (1 - HCT))` * *RC*: Reference concentration * *rel\_exp\_pls*: Relative expression in plasma * *rel\_exp\_bc*: Relative expression in blood cells * *f\_exp\_bc\_membrane*: Fraction expressed in blood cells membrane * *HCT*: Hematocrit * **Plasma (in organs except for ArterialBlood, VenousBlood, PortalVein):** Combination of the expression in plasma, in blood cells in the membrane facing plasma, and in vascular endothelium in the membrane facing plasma. `RC * (rel_exp_pls + rel_exp_bc * f_exp_bc_membrane * HCT / (1 - HCT) + rel_exp_vasend * f_exp_vasend_apical * V_vasend / V_pls)` * *RC*: Reference concentration * *rel\_exp\_pls*: Relative expression in plasma * *rel\_exp\_bc*: Relative expression in blood cells * *f\_exp\_bc\_membrane*: Fraction expressed in blood cells membrane * *HCT*: Hematocrit * *rel\_exp\_vasend*: Relative expression in vascular endothelium * *f\_exp\_vasend\_plasma*: Fraction expressed on membrane of vascular endothelium facing blood plasma * *V\_vasend*: Volume (endothelium) * *V\_pls*: Volume plasma * **Interstitial:** Combination of the expression in organ and in vascular endothelium in the membrane facing interstitial space. Be aware that depending on how the expression values for the organs have been obtained, explicit addition of the expression in vascular endothelium may result in higher calculated effective concentration. `RC * (rel_exp_org * f_exp_org_int * 1 / f_int + rel_exp_vasend * f_exp_vasend_tissue * V_vasend / V_int)` * *RC*: Reference concentration * *rel\_exp\_org*: Relative expression in organ * *f\_exp\_org\_int*: Fraction expressed interstitial * *f\_int*: Fraction interstitial (of total organ volume) * *rel\_exp\_vasend*: Relative expression in vascular endothelium * *f\_exp\_vasend\_tissue*: Fraction expressed on membrane of vascular endothelium facing tissue * *V\_vasend*: Volume (endothelium) * *V\_int*: Volume (organ interstitial) * **Intracellular:** `RC * rel_exp_org * f_exp_org_cell * 1 / f_cell` * *RC*: Reference concentration * *rel\_exp\_org*: Relative expression in organ * *f\_exp\_org\_cell*: Fraction expressed intracellular * *f\_cell*: Fraction intracellular(of total organ volume) * **Endosome:** `RC * rel_exp_vasend * f_exp_vasend_endosomes * 1 / f_endo` * *RC*: Reference concentration * *rel\_exp\_vasend*: Relative expression in vascular endothelium * *f\_exp\_vasend\_endosomes*: Fraction expressed in endosomes * *f\_endo*: Fraction endosomal (of total organ volume) ### Localizations, directions, and initial concentrations of transport proteins ![Localization Transporter](/files/Lp1SO9Xgs2SBQ03OBBk5) Transporters are located in the cell membranes, connecting two neighbor compartments. Four transport directions can be specified: * **Influx**: The substance is transported from the interstitial space or lumen to the intracellular space. * **Efflux**: The substance is transported from intracellular space to interstitial space or lumen. * **Bi-directional**: Facilitated transport along the concentration gradient. It is assumed that Vmax and Km values are equal for both directions. Only Michaelis-Menten kinetics can be used with this direction. * **Plasma to interstitial space** across endothelial border * **Interstitial space to plasma** across endothelial border As the model structure of PK-Sim does not explicitly contains membranes, expression of transporters is modeled in one of the neighbor compartments. In addition to the default transporter direction that is applied for all compartments, the direction can be specified for each compartment separately. As for proteins, the relative expression of a transport protein in an organ refers to the volume of organ tissue without blood cells and blood plasma. Following localizations are available: * **Blood cells**: Transport between blood cells and plasma Initial concentration: `RC * rel_exp_bc` * *RC*: Reference concentration * *rel\_exp\_bc*: Relative expression in blood cells * **Vascular endothelium**: Transport between blood plasma and the interstitial space of all organs. The transporter is placed in blood plasma with initial concentration given by the equation `RC * rel_exp_vasend * V_vasend / V_pls` * *RC*: Reference concentration * *rel\_exp\_vasend*: Relative expression in vascular endothelium * *V\_vasend*: Volume (endothelium) * *V\_pls*: Volume of plasma {% hint style="info" %} Be aware that depending on how the expression values for the organs have been obtained, explicit addition of the expression in vascular endothelium may result in higher calculated effective amount of the protein in tissue. {% endhint %} * **Organs**: In organs that do not have a lumen (bone, fat, gonads, heart, lung, muscle, pancreas, skin, spleen, stomach, and non-mucosal small and large intestine), with the exception of brain, transport proteins are always modeled in the interstitial space, transporting the molecules between intracellular and interstitial spaces. The initial concentration is given by the equation `RC * rel_exp_org * 1 / f_int` * *RC*: Reference concentration * *rel\_exp\_org*: Relative expression in organ * *f\_int*: Fraction interstitial (of total organ volume) * **Brain**: Transporter proteins in brain tissue are usually located in endothelial cells, transporting molecules across the blood-brain-barrier. This distinct nature of the brain tissue is captured in PK-Sim by locating the transport proteins by default into plasma compartment for the transport between plasma and interstitial space. The user can enforce expression of the transporter in interstitial compartment for the transport between interstitial and intracellular by setting the “Fraction expressed at blood brain barrier” and “Fraction expressed in brain tissue”. The concentrations in the respective compartments are calculated such that the total concentration in brain is `RC * rel_exp_org`. * The concentration in **plasma** is given by the equation `RC * rel_exp_brn * f_exp_brn_bbb * 1 / (f_vas * (1 - HCT))` * *RC*: Reference concentration * *rel\_exp\_brn*: Relative expression in brain * *f\_exp\_brn\_bbb*: Fraction expressed at blood brain barrier * *f\_vas*: Fraction vascular (of total organ volume) * *HCT*: Hematocrit * The concentration in **interstitial space** is given by the equation `RC * rel_exp_brn * f_exp_brn_tissue * 1 / f_int` * *RC*: Reference concentration * *rel\_exp\_brn*: Relative expression in brain * *f\_int*: Fraction interstitial * **Kidney** and **Liver**: In kidney and liver, transport proteins can be located between interstitial and intracellular spaces (defined by “Fraction expressed basolateral” and modeled in interstitial space) and/or on the apical site of renal tubule and hepatic bile duct cells (defined by “Fraction expressed apical” and modeled in intracellular space), respectively. Transporters located on the apical site are responsible for active excretion of the compounds into urine and bile in kidney and liver, respectively. * Initial concentration in **interstitial space** is given by the equation `RC * rel_exp_org * f_exp_org_basolatateral * 1 / f_int` * *RC*: Reference concentration * *rel\_exp\_org*: Relative expression in organ * *f\_exp\_org\_basolatateral*: Fraction expressed on the membrane between cellular and interstitial spaces * *f\_int*: Fraction interstitial (of total organ volume) * Initial concentration in **intracellular space** is given by the equation `RC * rel_exp_org * f_exp_org_apical * 1 / f_cell` * *RC*: Reference concentration * *rel\_exp\_org*: Relative expression in apical * *f\_exp\_org\_apical*: Fraction expressed on epithelial membrane * *f\_cell*: Fraction intracellular (of total organ volume) * **Mucosal tissue**: The apical site of mucosal cells is facing the gastrointestinal lumen and facilitates the absorption or active excretion, while the basolateral site connects the intracellular and interstitial spaces. * Initial concentration in **interstitial space** is given by the equation `RC * rel_exp_org * f_exp_org_basolatateral * 1 / f_int` * *RC*: Reference concentration * *rel\_exp\_org*: Relative expression in organ * *f\_exp\_org\_basolatateral*: Fraction expressed on the membrane between cellular and interstitial spaces * *f\_int*: Fraction interstitial (of total organ volume) * Initial concentration in **intracellular space** is given by the equation `RC * rel_exp_org * f_exp_org_apical * 1 / f_cell` * *RC*: Reference concentration * *rel\_exp\_org*: Relative expression in apical * *f\_exp\_org\_apical*: Fraction expressed on epithelial membrane * *f\_cell*: Fraction intracellular (of total organ volume) ## The workflow If you want to use the gene expression databases, ensure that they are correctly installed and linked to the application, see [Options](/v12/working-with-pk-sim/pk-sim-documentation/pk-sim-options). The workflow of integrating protein data with PBPK models comprises the following steps: 1. Identification of relevant metabolizing enzymes, transport proteins, and protein binding partners for the compound of interest (*your internal research or literature*) 2. Determination of organ and tissue specific distribution of protein concentrations (PK-Sim® supports this task with a built-in database) 3. Identification of cellular location of proteins (*your internal research or literature*) 4. Devise applicable kinetics and adjust kinetic parameters (*modeling, your internal research or literature*) ## Modeling protein/drug interactions in PK-Sim® The distribution of a protein (metabolizing enzyme, transporter protein, or a protein binding partner) in the modeled organism is defined by an Expression Profile in the "Expression Profiles" building block. The expression profile is then linked to the individual (see [PK-Sim® Creating Individuals](/v12/working-with-pk-sim/pk-sim-documentation/pk-sim-creating-individuals)), and the interaction between the protein (e.g., a metabolization reaction) is defined in the "Compounds" building block, see [PK-Sim® Compounds: Definition and Work Flows](/v12/working-with-pk-sim/pk-sim-documentation/pk-sim-compounds-definition-and-work-flow). ## Definition of new Expression Profile in PK-Sim® To create a new expression profile, do one of the following: * Click **Expression Profile** in the **Create** Group of the **Modeling** Tab and select the protein type (metabolizing enzyme, transport protein, or protein binding partner) * Right mouse click on **Expression Profiles** in the **Building Block Explorer** and select **Add Expression Profile...** The following dialog will open in which the properties of the expression profile can defined: ![Create Expression Profile (for a metabolizing enzyme)](/files/Tp8c1KAXSGZyn38OucYI) * **Species**: Species for which the expression profile will be defined. Note: The profile can only be added to an individual with the same species! You need to create separate expression profiles for each species where the protein should be used. * **Metabolizing Enzyme**: Name of the enzyme. You can select from a predefined list of common proteins or enter a name * **Phenotype**: A free text allowing you to specify the expression profile. For example, you might want to create different profiles for the CYP3A4 enzyme in human for poor vs extensive metabolizer. In this case, **poor** and **extensive** could be used. Alternatively, you might want to create a profile for a **healthy** vs **sick** individual etc... {% hint style="info" %} The combination {Species, Protein, Phenotype} needs to be unique in the project. It will define the name of the expression profile building block {% endhint %} ## Editing an Expression Profile in PK-Sim® There are two ways of editing an expression profile, either via a database query using the PK-Sim® gene expression database, or through direct entering of protein expression to a list of organs and tissues. ### Editing protein expression manually If you know expression of proteins in one or several organs you can define the expression data manually. We will explain settings in detail in [Settings in the protein expression tab](#settings-in-the-protein-expression-tab). ### Editing protein expression by querying the expression database {% hint style="info" %} To be able to query expression data from a database you have to select a database for the current species in PK-Sim ®options (see [PK-Sim® Options](/v12/working-with-pk-sim/pk-sim-documentation/pk-sim-options)). {% endhint %} Click on **Database Query**. A database query wizard will open, using the name of the protein as a default search criteria. This is discussed in more detail in “[Advanced Analysis](#advanced-analysis)”. Here we walk you through the simplest possible process. ### Adding search criteria The first panel of the database search wizard allows you to enter a search term in the search bar ![Expression Protein Selection](/files/ZgRAjC1pOyfi4opzq5Zr) This term can be anything from gene name, gene symbol, or parts of the description. {% hint style="info" %} The term is automatically enclosed by wildcards. You can turn off this default behavior by enclosing the term with “quotes”. As wildcards you can use a percent sign (%) or a star (\*) for multiple characters and a question mark (?) or underscore (\_) for a single character. {% endhint %} Once you hit enter, you will see a list of database entries that match your search. Several details are displayed like: * Gene Name * Name Type (e.g. is the gene name a synonym) * Gene symbol (this is the most authoritative naming convention) * (entrez) Gene ID * Official full name for the protein or gene Select the appropriate entry in the list of search results (or refine your search). {% hint style="info" %} The (entrez) gene ID is also a hyper link to the NCBI gene page where you can find additional information about the gene. {% endhint %} {% hint style="info" %} A hit row is highlighted in gray if the gene is known in the database but there are no expression data available. In this case the other tabs are disabled. {% endhint %} ### Reviewing measured gene expression In the upper panel you can find a table of gene expression values. The table is organized with tissues in rows, and data sources in columns. {% hint style="info" %} You can select one or several cells with the mouse (press left mouse key down), copy the content with **Ctrl+C**, and paste the values into another application, e.g. Microsoft Excel,® with **Ctrl+V**. {% endhint %} The lower panel gives a graphical representation of the gene expression values. In the table (upper panel), the data can be filtered by several criteria. (REF: How to use the database query wizard). ![Expression Data Analysis](/files/4oKeCCRH9hPDYFQtNc3g) ### Reviewing data before transfer In the data transfer overview tab the data to be transferred are compiled for reviewing. Note, that relative expression values are given. In the upper part of the windows one or more radio buttons are displayed. The radio buttons are used to select the appropriate data source. Currently, Array, EST or RT-PCR can be selected. After selecting one of the data sources the expression levels in different PBPK containers are displayed in the lower panel. Select the most appropriate data source and click **OK** to close the database query wizard. The expression data is transferred to PK-Sim® ![Expression Data Transfer](/files/v50wAYR522IGjOYFOiWp) {% hint style="info" %} The Array Database is best in terms of the number of genes covered (essentially the complete genome), RT-PCR provides the most accurate measurements, and EST data in some cases covers unusual types of tissue. Use the data sources that has the most appropriate coverage of tissues for your purpose. Array data is usually a good choice. {% endhint %} {% hint style="info" %} When using several proteins different data sources for different proteins may safely be used. {% endhint %} ![Expression Input Form With Transferred Data](/files/M0DrWoaiaebrRnsR2iW0) {% hint style="info" %} The complete data set is stored within the PK-Sim® project. If you re-enter the query by selecting the **Edit...** menu item from the context menu of a defined protein, all data will be taken from the internally saved data set. To force access to the database you need to re-query the protein in the protein selection form. {% endhint %} {% hint style="info" %} You can rename a defined expression profile within your PK-Sim® project by selecting the **Rename...** menu item from the context menu of a defined expression profile. This name has no impact on the query and is only used to identify the protein within the PK-Sim® project. {% endhint %} ## Settings in the protein expression tab In the upper section, the following entries can be adjusted: * **Reference concentration**: Enter the molar concentration of the protein in the organ with the highest enzyme concentration (typically the liver). This is useful as you will later solely enter relative enzyme concentrations. If you do not know the absolute concentration in the organ with the highest expression level you can leave this entry at its default value of 1.00 μmol/mg and adjust the active process, e.g. via the Vmax value. See [Reference Concentration](#reference-concentration) for a more detailed discussion of the Reference concentration. * **t1/2 (liver)** and **t1/2 (intestine)**: Half-life of the protein turnover in the liver and in the intestine. * **Ontogeny like**: A list of typical enzymes and locations is shown for which the PK-Sim® software already knows ontogenies. Ontogenies are age-depending changes of enzyme concentrations in the respective organ or tissue. Currently, ontogeny information is only available for the liver and for the intestine and restricted to a selection of important enzymes. {% hint style="info" %} Detailed information on the integrated enzyme ontogenies is available in the separate documentation [PK-Sim® Ontogeny Database](https://github.com/Open-Systems-Pharmacology/OSPSuite.Documentation/blob/master/PK-Sim%20Ontogeny%20Database%20Version%207.3.pdf) {% endhint %} If the selected enzyme is recognised and ontogeny information is available, that enzyme is preselected. Otherwise, from this list the ontogeny of an enzyme/ protein may be selected. The button to the right of the list can be used to visualise the ontogeny. The fraction of adult protein content in a specific organ is plotted against age. The gene expression that is used in the simulation incorporates the age- dependency of the ontogeny. In the lower section, values of relative expression can be edited for individual tissues, vascular system and GIT - Lumen. Additionally: * For metabolizing enzymes and protein binding partners: * The localization in tissue, blood cells and vascular endothelium can be modified (see [Localizations and initial concentrations of enzymes](#localizations-and-initial-concentrations-of-enzymes) for explanation of the various parameters). ![](/files/kQpkQ9NJ1fJKqIxVrfiC) Activating/deactivating checkboxes in each of these 3 localization groups changes some parameter values and shows/hides parameters following the following logic: * If only one option in a group is activated: corresponding `fraction expressed` parameter will be set to 1; other `fraction expressed` parameter(s) of this group will be set to 0; all `fraction expressed` parameters of the group will be hidden. E.g. activating the checkboxes as in the screenshot above will result in: * **Tissue** localization parameters: * `Fraction expressed intracellular = 1` (parameter is hidden) * `Fraction expressed interstitial = 0` (parameter is hidden) * **Blood Cells** localization parameters: * `Fraction expressed in blood cells = 1` (parameter is hidden) * `Fraction expressed in blood cells membrane = 0` (parameter is hidden) * **Vascular Endothelium** localization parameters: * `Fraction expressed in endosomes = 1` (parameter is hidden) * `Fraction expressed on plasma-side membrane of vascular endothelium = 0` (parameter is hidden) * `Fraction expressed on tissue-side membrane of vascular endothelium = 0` (parameter is hidden) * If more than one option in a group is activated: corresponding `fraction expressed` parameters are shown and can be edited by user. E.g. for the selection below: ![](/files/Be7vIr2PHt56tCIkpye4) * **Tissue** localization parameters: * `Fraction expressed intracellular` is shown and can be edited by user * `Fraction expressed interstitial` is shown (not editable; always set as `1 - Fraction expressed intracellular`) * **Blood Cells** localization parameters: * `Fraction expressed in blood cells` is shown and can be edited by user * `Fraction expressed in blood cells membrane` is shown (not editable; always set as `1 - Fraction expressed in blood cells`) * **Vascular Endothelium** localization parameters: * `Fraction expressed in endosomes` is shown and can be edited by user * `Fraction expressed on plasma-side membrane of vascular endothelium` is shown and can be edited by user * `Fraction expressed on tissue-side membrane of vascular endothelium` is hidden and always set to `1 - (Fraction expressed in endosomes + Fraction expressed on plasma-side membrane of vascular endothelium)` ![](/files/iztIdNMOdsuXQadScJvM) * If all options in a group are deactivated: all corresponding `Fraction expressed` parameters are hidden AND all corresponding relative expressions are automatically set to 0. E.g. deactivating both options "*Blood cells intracellular*" and "*Blood cells membrane*" will not only hide the parameters `Fraction expressed in blood cells` and `Fraction expressed in blood cells membrane` but also set `Relative expression in blood cells` to 0 and hide it. In such a case, before setting relative expressions to zero a warning is shown to the user to avoid the loss of information: ![](/files/UmZXHSsEC9dbFT9YgJRK) * For transport proteins: * For some organs, `Fraction expressed apical` can be set (see [Localizations, directions, and initial concentrations of transport proteins](#localizations-directions-and-initial-concentrations-of-transport-proteins) for explanation of the various parameters). * Transporter direction can be set to **Efflux**, **Influx** or **Bi-Directional**. * Transporter direction can be set **for each organ independently**. In order to change the direction in all organs simultaneously, change the selected value in the "Default Transporter Direction" selection box. {% hint style="warning" %} The value of the "Default Transporter Direction" is only used to reset all organ transporter directions to the given type and is not used in the model. E.g. if the user sets the default transporter direction to **Efflux** in all organs and then changes it to **Influx** in one organ: in this particular organ the Influx transporter will be created! {% endhint %} {% hint style="warning" %} The transporter direction **Pgp-like** is, starting with version 11 of PK-Sim, marked as **\[DEPRECATED]** and should not be used anymore. It is only available for compatibility reason with older models and will be removed in a future version of the software. {% endhint %} ![Transporter directions](/files/2kfV7ljDcWKvC8GVVLbH) * For all proteins: * Initial concentration in every compartment (which is calculated based on the reference concentration, relative expression values and localization settings as described above) is hidden as per default. To show and **to edit** it (if required), the *Show initial concentration* checkbox must be activated: {% hint style="warning" %} Most initial concentration values can only be computed in the context of an individual the expression profile is linked to. If you enter a specific value, it will be used in all individuals that use this expression profile and will effectively replace the formula described previously. {% endhint %} ![Show/Edit (effective) initial concentration](/files/LpGNkgxMiRK6qmihShq0) ## Advanced Analysis In this section the more advanced features of the expression database integration are explained. ### Pivot Table In the upper section of the “Data Analysis tab page” the expression data is compiled in a pivot table. With the help of a pivot table cross tabulations are easily possible. You can drag fields to use them as additional row or column headers. The table changes dynamically. ![Expression Data Analysis Pivot Table](/files/iWY23FaOu8Ynu5daXJTs) {% hint style="info" %} You can change the X-Axis field used by the corresponding chart by double clicking on a row header. This feature is only available for fields with no empty values. {% endhint %} {% hint style="info" %} You can change the series building field used by the corresponding chart by double clicking on a column header. This feature is only available for fields with no empty values. {% endhint %} {% hint style="info" %} You can reset all fields back to their default position by double clicking on a filter field header. The fields used in the chart are also reset by that action. {% endhint %} ## Filtering Data Each field can be used for filtering. To open the filter dialog click on the filter symbol ![Image](/files/w00okRh7xsKZWKcFHWb5) which is shown in the field header when hovering over a field. ![Field Filter Dialog](/files/B3ZtTSh9uOiiv30mol8T) By ticking the check boxes you can toggle the filtering of individual values. {% hint style="info" %} The buttons in the upper area have the following meaning: * The ![Image](/files/PXQDeavopcgKaoGlPLJn) button can be used to limit the list of values to only those that are currently visible. If you would have added a filter on another field some values might are unreachable. Those values would be hidden. * The ![Image](/files/WKAU368t6QOx9yMM80ye) button can be used to change the check box into an option box which means that you can only select one filter value at a time and that the previously selected value gets automatically deselected by selecting a new value. * The ![Image](/files/RsvjWCaHHzLjv3a5FfO0) button can be used to invert the selected filter values which means that every selected value gets deselected and vice versa.. {% endhint %} The respective active filter is shown right under the table. ![Expression Data Analysis Pivot Table With Filter](/files/UBrqZcxUHgKY33QcUpJR) Click on **Edit Prefilter** to open a dialog for editing complex filter conditions. ![Prefilter Dialog](/files/JvQPWbiZBkYtNTkM0957) To add a condition for the age of the population used in the expression data measurements you can add a condition in the prefilter dialog with the following steps: * First save the current condition to the clipboard by selecting the topmost logical operator and pressing **Ctrl+C**. * Change the topmost logical operator to “And”. * Restore the original condition by pressing **Ctrl+V**. * Add a new condition by pressing the button behind the topmost logical operator “And”. * Select the column “Age(Minimum)” and select the condition operator “Is greater than or equal to” and enter the value “18”. Now the condition has changed and only data from adults will be used ![Prefilter Dialog With Age Condition Added](/files/rKdhNo0iBQRey8tk6W8b) {% hint style="info" %} For filtering age ranges of populations you might find it more convenient to use the \[Age(Minimum)] and \[Age(Maximum)] columns. {% endhint %} ### Edit Mapping A default mapping maps measured expression data of tissues to PK-Sim® containers. This mapping can be changed by users. If you double click on the value of a container or tissue the edit mapping dialog opens. ![Edit Mapping Dialog (End of List)](/files/SXdYtvRuBEFQaWb2V7pm) On the left hand side of the dialog the containers with their corresponding icons are shown and on the right hand side the currently mapped tissue is shown. Blue font means that there is no expression data available for that tissue. At the end of the list all tissues are displayed for which data could be found but which are not already mapped. ![Edit Mapping Dialog (End of List)](/files/xPRjoQggFBPcAhMUHXj2) It is possible to map one tissue to multiple containers. For example the Small Intestine is mapped by default to several areas of the GI tract. In the navigator panel of the edit mapping dialog, the following buttons can be used: * The ![Image](/files/I7ADoXBtdztnGLkSjFIZ) button brings you to the first record. * The ![Image](/files/eXxBFOidIHuNB90c6nf1) button brings you 10 records backwards. * The ![Image](/files/USjyCuV7cXOpYeLG9F13) button brings you to the previous record. * The record counter ( ![Image](/files/7KU5rMxJNzqeL1QsKHzM)) shows you the actual position and the total number of records. * The ![Image](/files/EUOCXXclfQQ71nbrZfIN) button brings you to the next record. * The ![Image](/files/t0Tm9uBuTbbgU2Cx0paU) button brings you 10 records forwards. * The ![Image](/files/Kbsq4WrcCxw6Ilwg18LV) button brings you to the last record. * The ![Image](/files/cOPfW9Dvk4TABuhrpCCu) button enters the edit mode. * The ![Image](/files/pzb2fc38J2ygjJa1WxK3) button leaves the edit mode and accepts the changes. * The ![Image](/files/Qg3dY0mq0uZzmzHizksv) button leaves the edit mode and rejects the changes. Even though you can accept changes in the edit mode, ultimately they will only be saved by leaving the dialog and pressing the **OK** button. Changes done within the dialog are highlighted with orange background color. ![Highlighting of Changes](/files/GInzOD4dnlyM76hDhrci) If you want to discard all changes you can just leave the dialog with the **Cancel** button. # Creating Individuals In the building block **Individual** the properties of individuals are defined. In the database underlying PK-Sim®, anatomical and physiological information on various animal species, as well as humans of different populations, genders, and ages, is provided. The algorithm for creating virtual individuals differs for animals and humans: * In the case of **animal species**, no age-dependent distribution information for the anatomical and physiological parameters is included in the database so far. The generation of an animal with a predefined body weight is thus done by linear scaling of an average animal of the given species. Consequently, all organs always contribute to the same relative extent to the total body weight, and differences, e.g., related to growth or to different races of the respective animal species are not taken into account. * For **humans**, the population parameters database that comes with PK-Sim® includes information on the dependence of anatomical and physiological parameters relevant for PK-Sim® such as organ weights, blood flow rates, or tissue composition on age, gender, body weight, body mass index, which have been collected in a comprehensive literature search. Thus, when creating an individual of a given **Age**, **Weight**, and **Height**, the parameters will be adjusted based on the information included in the underlying database. There are three classes of parameters that are adjusted: * Organ volumes * Further parameters for which distribution data are available in the database, e.g. the hematocrit value. * The volume fractions, which are scaled using a global scale factor taken from the database {% hint style="info" %} Please note that the volume of fat tissue is not optimized by the algorithm as this value is used to match the target body weight. {% endhint %} ## Definition of new Individual in PK-Sim® * Click on **Individual** in the **Create** Group of the **Modeling** Tab or * Right mouse click on **Individuals** in the **Building Block Explorer** and select **Add Individual...** or * Use the shortcut **Ctrl+Alt+I** A dialog will pop up in which the properties of the individual can be specified. First, new individuals are initialized by giving them a **Name** in the respective input field. These names are then used to identify them when their properties are saved in the project and/or as templates. In addition, names are used for identification of individuals in the simulation. Second, the properties of individuals can be set or changed: ![The Create Individual dialog. Here, the properties of a standard European individual are shown.](/files/LVMBG2mbWrsujDeHK2ag) The **Create Individual** window is subdivided into three tabs: **Biometrics, Anatomy & Physiology**, and **Expression**. ### Biometrics In the first drop-down menu you can choose from the following species: * Human * Monkey * Beagle * Dog * Minipig * Rat * Mouse * Rabbit * Cat * Cattle ### Human If **Human** is selected, you can select one of the following populations from the next drop-down menu: * East Asian (Tanaka, 1996) \[[74](/v12/references/references#74)] * Black American (NHANES, 1997) \[[82](/v12/references/references#82)] * European (ICRP, 2002) \[[84](/v12/references/references#84)], \[[113](/v12/references/references#113)] * Mexican American -White (NHANES, 1997) \[[82](/v12/references/references#82)] * White American (NHANES, 1997) \[[82](/v12/references/references#82)] * Japanese \[[67](/v12/references/references#67)] * Preterm \[[111](/v12/references/references#111)] * Pregnant (Dallmann et al. 2017) \[[107 - 110](/v12/references/references#107)] In the following drop-down menu, the gender is specified. Further below, the **Individual Parameters** can be defined. In the case of the human Asian, Black American, European, Mexican American, and White American populations, the individual is characterized by the following parameters: * Age: The age in units of year(s), month(s), week(s), or day(s). * Weight: The body weight in units of kg or g. * Height: The body height in units of cm or m. By clicking on the **Mean** button, the average body weight and height of the individuals of the given population as well as gender and age will be generated based on the database information. If as a special human population **Preterm** is selected, an additional age scale has to be taken into account. Preterm neonates are characterized by their gestational age (GA), which ranges between about 24 and 37 weeks, and their postnatal age (PNA). In the model, preterm neonates catch up growth during their first two years of life so that there are no differences in a >2 years old individual of the same race and gender born preterm or born term. ![Postnatal growth curves for preterm infants pooled into different weight classes up to two years (black solid lines) compared to term born infants matched to the growth charts of the “Centers for Disease Control and Prevention” (CDC, shaded area).](/files/kBK3M8qNpgbsqU79hm2J) {% hint style="warning" %} Oral administration to preterm neonates is, so far, not possible in PK- Sim®. The parameters relevant to oral administration are all set to "0" so that the fraction of dose absorbed and, in addition, the distribution of drugs into the mucosa irrespective of the administration route are disabled. {% endhint %} {% hint style="info" %} Please note that gender-specific information for all parameters except body weight and height (biometrics) was not available for preterms.Therefore, it is an assumption that for a given body weight the organ weights and blood flow rates are equal for males and females. {% endhint %} #### Disease State Depending on the selected population, a disease state for the selected individual can be specified. By default, the individual will be created as **Healthy**. #### Healthy Healthy individuals in PK-Sim are representative of the general population of individuals in the specified ethnicity and/or geographic area. These individuals are parameterized under the assumption that they have no chronic or comorbid disease states that would have a relevant effect on anatomy, physiology or drug disposition. #### Chronic Kidney Disease (CKD) Chronic kidney disease is renal impairment lasting at least 3 months. The disease is staged according to eGFR. Over time, multiple other body systems are also affected. To apply this disease state to an individual in PK-Sim, first select the targeted eGFR. Accordingly, the individual will display changes in GFR, kidney volume, kidney blood flow, plasma protein binding, hematocrit, gastric emptying time, and small intestinal transit time. This parameterization is for individuals with CKD who are not on dialysis. It does not modify the expression or activity of enzymes or transporters - only foundational anatomy and physiology. Users should consult scientific literature for information how the relevant enzymes and transporters for their purposes may be affected. For more information on the implementation, please refer to \[[122](/v12/references/references#122)] ### Animal species If one of the animal species, i.e. **Monkey, Beagle, Dog, Minipig, Rat** or **Mouse** is selected, the menu items are slightly different. {% hint style="info" %} Please note that PK-Sim® does currently not distinguish between male and female animals. Animal models represent an average adult animal of the species or breed. {% endhint %} If desired, the body weight of an animal can be changed under **Individual Parameters**. By changing the body weight of the animal, PK-Sim® automatically scales the weight of the different organs ( see [**Anatomy & Physiology**](#anatomy--physiology) tab) by keeping their relative contribution to the total body weight constant. Likewise, the organ blood flow rate will be re-calculated by keeping the organ specific blood flow rate, i.e. the blood flow rate per kg of tissue weight. {% hint style="info" %} Significant breed-specific differences exist for some animal species. For example, a Beagle dog obviously has a different physique than a Labrador and the body weight of an adult Yucatan minipig doubles that of a Göttinger minipig. See below for tips to determine how each species is defined in PK-Sim®. {% endhint %} * For monkeys, the default values represent an average monkey with a body weight of 5.6 kg. The monkey-specific physiological parameters were derived for macaques such as rhesus and cynomolgus monkeys \[[98](/v12/references/references#98)]. * The default dog-specific physiological parameters were obtained from literature and represent an average dog with a weight of 13.7 kg. Breed specific differences are not taken into account. Still, for the most popular breed of dogs, the beagle, anatomical and physiological information specifically representing an adult beagle dog that weights 10.5 kg is implemented \[[1](/v12/references/references#1)]. * For minipigs, the default body weight is 40 kg. An important feature of the minipig is the reported delay in gastric emptying. Furthermore, emptying appears to be incomplete, so there may be food present in the stomach for 24 hours a day. The high variability in gastric pH and emptying should be taken into account, particularly when monolithic controlled release and enteric-coated dosage forms are intended to be simulated. * For the rat-specific physiological parameters affecting oral absorption from the GI tract see \[[93](/v12/references/references#93)]. An important feature of this species is that the rat lacks a gallbladder. As a result, bile fluid is secreted continuously in dilute form, which has an important effect on biliary clearance and entero-hepatic circulation (see [PK-Sim® - Events](/v12/working-with-pk-sim/pk-sim-documentation/pk-sim-events)). * If mouse is selected, the anatomical and physiological data are set at default values for a mouse with a mean weight of 20 g. * For rabbits, the default body weight is 2.5 kg. For the parameter values not found in the literature, the mouse PBPK model parameters were transferred and used, as it is the closest animal species to the rabbit among the species available in the physiology database (e.g., mouse retains a gallbladder unlike the rat). \[[112](/v12/references/references#112)] * Currently, only for mouse, monkey and human species specific values for the concentration of the FcRn receptor, the concentration of the endogenous IgG and the affinity of the endogenous IgG to the FcRn receptor (needed for the **Model for proteins and large molecules**) are available. For all other animal species, the concentrations are taken from the human model and the Kd(FcRn) of the endogenous IgG in endosomal space is set to 0.75 µM. Irrespective of the species chosen, the **Calculation Method** for the estimation of the surface area of the capillary endothelium has to be selected. The endothelial surface area is needed for calculation of the rate of permeation through the endothelial barrier between plasma and interstitial space, which is determined by the permeability - surface area product. The drug dependent specific organ permeability can be defined in the **Compound** building block (see [PK-Sim® - Compounds: Definition and Work Flows](/v12/working-with-pk-sim/pk-sim-documentation/pk-sim-compounds-definition-and-work-flow)). Literature for capillary surface areas for the different organs and species is rather limited. Therefore, PK-Sim® provides two heuristics to estimate the capillary surface area of the organs, which can be selected from the drop-down menu 1. **Organ vascularization (default method)**. The capillary surface area (SA) is estimated by ![Image](/files/zhvndK9t8Udbcp4XbIaM) , with the constant of proportionality k, the fraction of vascular space of an organ ![Image](/files/GtdH95ys1Sj8X1DaASnN), and the organ volume ![Image](/files/9fV00SYUisdqkIEqsNSY). The idea behind this heuristics is the following: with the assumption that the morphology of the vascular tree is similar in each organ, the specific surface area per organ volume can be estimated by the capillary density of an organ, which in turn can be estimated by the fraction of vascular space of an organ. 2. **Blood flow.** The capillary surface area is estimated by ![Image](/files/zor0Sb02fwOsi5wIIY2P)\ , with the constant of proportionality $$k$$, the organ blood flow $$Q\_{organ}$$, the shape factor $$beta$$ (default: $$beta=1$$). The permeability-surface area product ![Image](/files/cl6rBeodWXcJLGsh7NnP) is related to the extraction $$E$$ by ![Image](/files/Ug9a0wKWSNdqXv2ISvk7) \[[8](/v12/references/references#8)]. With the assumption that the extraction of drug in each organ is equal, ![Image](/files/24qFd1XWHdARLiRTD4dR) is obtained. If it is further assumed, that the permeability is equal for each organ one obtains ![Image](/files/ZAF6K0pg2YLj3zvbXwYQ). ### Anatomy & Physiology Anatomical and physiological properties in PK-Sim® are set at default values for a mean representative of a species. These default values were carefully selected from literature. In the human species module, also the mean values for children of all age groups are included. For some purposes, e.g. to simulate pathological disorders, it is desirable to change these values. This can be done in the **Anatomy & Physiology** tab, in which the parameters are, using the default settings, displayed in a tree structure on the left hand side. By default, a **Simple** view of the various properties is displayed, in which only the most relevant parameters are shown. Using the drop-down menu at the bottom of the window, you can switch to the **Advanced** tree view or to the **Hierarchy** view. In the **Simple** and the **Advanced** view, the parameters are grouped based on function whereas in the **Hierarchy** view, they are listed according to the internal model structure. Please note that only containers comprising visible parameters are displayed. There are additional parameters in the model which are not displayed in PK-Sim®. They are, however, displayed in MoBi®. For details please see [Working with MoBi®](/v12/working-with-mobi/mobi-documentation/first-steps). The tree view shows only drawings that are currently open. To access the various parameters, 1. Click on the light grey arrow to open the respective tree view node 2. If present, click on the next light grey arrow to open the subsequent level of the tree view 3. Click on the desired parameter group {% hint style="info" %} Use the **Filter** function above the tree view to find parameters more quickly. {% endhint %} In the window on the right hand side, the details of the respective parameter group will be shown. Typically, the first column(s) contains the **Name** of the parameter and/or its location (i.e. the organ or segment). In the next column, the default **Value** for the parameter in the given organ or segment for the species selected is provided together with the corresponding unit. For humans, the column **Percentile** depicts the percentile within the respective population. If an average subject is selected, this bar should be equal or at least close to 50%. In the last column, you can define parameters as **Favorites** in order to select certain parameters, e.g. if they have to be changed frequently. Parameters defined as favorites will be listed in the undermost node of the tree view and are thereby easily accessible. {% hint style="info" %} The order of the columns can be changed manually. Drag the column header to the desired position to change the sequence of columns. {% endhint %} {% hint style="info" %} The column by which the parameters are grouped can be selected. Drag the column header to the top of the table into the group box. {% endhint %} To change the value of a parameter, do one of the following * Enter a new value in the respective input field * Multiply the default values with the scale option There are three types of parameter values: 1. Parameter values displayed by default on a white background represent constants values. By changing the parameter value, the default value will be overwritten and the background of the field turns yellow. To reset the parameter value to default click **Reset parameter to default** or use the **Rollback** function of the **History manager**, see [Shared Tools - History manager and history *reporting*](/v12/shared-tools-and-example-workflows/history-manager-history-reporting). 2. Parameter values displayed by default on a light blue background represent parameters calculated using a formula. By changing these values, the formula is overwritten and the background of the field turns yellow. To reset to the default value(s) click **Reset parameter to default** . 3. Parameter values displayed by default on a grey background represent values which cannot be changed by the user, because otherwise a fundamental relationship could be destroyed. {% hint style="info" %} The background colors that indicate the different types of parameters (1.-3.) can be changed by the user. For details please see [PK-Sim® - Options](/v12/working-with-pk-sim/pk-sim-documentation/pk-sim-options). {% endhint %} For some parameters, reasonable ranges are defined. For example pH values should be less than or equal to 14. In case a value outside this range is defined, a warning appears and the window cannot be closed without setting the parameters to a reasonable value. #### Liver Zonation The **Advanced** view offers the implementation of a zonated liver into an individual. Metabolic pathways in the liver are spatially separated along the liver sinusoids \[[29](/v12/references/references#29)]. Splitting the liver into more than one zone will improve simulation accuracy. As shown below, the liver is not zonated per default (only periportal zone). Upon zonation, the liver is split into a periportal and a pericentral zone. The parameter **Fraction of periportal zone** defines the ratio of the zone volumes and the surface areas and is set to 50% per default. ![The Advanced view in the Anatomy/Physiology tab offers the use of a zonated liver.](/files/8ZwsWMc4AlaiypOLjQF6) Switching between zonated and non-zonated liver does not alter the model structurally, but changes only the model parameterization. The relative expressions for enzymes, transporters and binding proteins can be set independently for both zones. The relative expression in the pericentral zone have no effect if the liver is not zonated. Currently, the PK-Sim gene expression database delivers the same relative expression for both zones for all proteins, but this will be improved in the future. {% hint style="warning" %} Please note that when switching to another species on the Biometrics tab all parameters of the individual defined in the **Anatomy & Physiology** tab and in the **Expression** tabs, including applied changes (e.g. active processes), are overwritten. {% endhint %} {% hint style="info" %} **User Defined** parameter node shows an overview of all parameters changed by the user in the individual. {% endhint %} ### Expression In the **Expression** tab, all relevant enzymes, transport proteins and protein binding partners can be defined for the selected individual. For details on how to create an expression profile, please see [PK-Sim® - Expression Profile](/v12/working-with-pk-sim/pk-sim-documentation/pk-sim-expression-profile). To add a protein to the individual, right click on the corresponding protein type in the tree view and select the corresponding action in the context menu ![Add a metabolizing enzyme](/files/5LDeeeNlebzx0B043ZV0) This will open a view to select the expression profile to link with the individual. Either select an existing expression profile, load one from template or create a new one by clicking on ![Select an expression profile](/files/UVDvy7bBdA6pzhkUKSE4) Once the expression profile is selected, it will be linked to the individual and displayed in the **Expression** tab. ![Expression profile linked to individual](/files/aJS2ta5rgfvGmBjSkUxc) This is the only instance in PK-Sim where a a building block is referencing another building block. {% hint style="warning" %} Please note that when adding an expression profile to an individual, the expression profile is linked directly to the individual. Any modification performed in the expression profile will be immediately reflected into the individual. This is the reason why all parameters are read-only in the individual. {% endhint %} ### Editing and Scaling Individual Properties To edit properties of existing individuals: 1. Right mouse click on the respective individual in the **Building Block Explorer** 2. Select **Edit...** or simply double click on the existing individual in the **Building Block Explorer**. This will open the properties window of the individual. The properties defined in the **Anatomy & Physiology** tab and those defined in the **Expression** tab can be set or changed appropriately. Changes are saved by simply closing the window (click on ![Image](/files/GeHXwqvOAa75Sa1A3G4d) ). Please note that the **Biometrics** of an existing individual cannot be changed later on. In order to change the **Biometrics** please create a new individual or use the scale function. Using the scale function transfers modifications at the individual and expression levels to the scaled individual. In order to **scale** an existing individual: 1. Right mouse click on the respective individual in the **Building Block Explorer** 2. Select **Scale...** The **Scale Individual** dialog opens, which is divided into four tabs: **Biometrics**, **Scaling configuration**, **Anatomy & Physiology**, and **Expression**. Details about the three tabs **Biometrics**, **Anatomy & Physiology**, and **Expression** have already been described for the **Create Individual** dialog (please see above). Here, only details about the tab **Scaling configuration** are given: If, and only if, certain individual parameters such as organ weights or blood flow rates were modified in the base individual used for scaling, these parameters will be listed in this tab. This is e.g. the case if an individual with specific characteristics due to certain diseases (e.g. renal or hepatic impairment) was created and you would now like to transfer these changes to another individual. The following six columns appear in the **Scaling configuration** tab: * **Parameter**: The name of the parameter modified in the base individual used for scaling. * **Source default value**: The original value of the parameter in the base individual according to the database underlying PK-Sim®. The source default value depends on the biometrics (race, age, and gender) of the base individual. * **Source value**: The modified value of the parameter in the base individual. * **Default value**: The default value of the parameter in the scaled individual according to the database underlying PK-Sim®. This value will differ from the source default value if the scaled individual is characterized by different biometrics (race, age, and/or gender). * **Scaled value**: The modified value of the parameter in the scaled individual. This value depends on the scaling method selected in the last column (Scaling method): * **Scaling method**: Select between four options for the scaling method from the drop-down menu: 1. **Same percentile**: This method is only available in the case of distributed parameters such as organ weights and blood flow rates in human populations. If a modification was made in the base individual the parameter value will not represent an average value anymore, i.e. it will not lie on the 50th percentile of the distributed parameters for the given population (characterized by race, age, and gender). Choosing this option, the same percentile will be used for your scaled individual of the selected population based on the PK-Sim® database. 2. **Use default value**: The modification made in the base individual will not be transferred to the scaled individual. Instead, the default value of the parameter in the scaled individual according to the database underlying PK- Sim® will be used. 3. **Use source value**: If a modification was made in the base individual the identical parameter value will be used in the scaled individual. Please note that for most parameters this is only a reasonable option if the biometrics (race, age, gender) of the base and the scaled individual are identical or at least similar. 4. **Same ratio**: The ratio of the source value divided by the source default value is multiplied by the default value of the scaled individual. The line **Target weight**, which appears only on the top of this window if modifications in organ volumes were made in the base individual, indicates the body weight of the scaled individual. A modification of organ volumes will automatically lead to a change in total body weight, which is the sum of all organ weights. Thus, if the default value of an organ weight is changed, the new body weight, which is no longer in agreement with the body weight previously selected on the biometrics tab, will be shown. ### Clone an Individual To clone an individual in the project: 1. Right mouse click on the respective individual in the **Building Block Explorer** 2. Select **Clone...** 3. Set an alternative name for the clone and enter a description if desired 4. Confirm and close the window by clicking **OK** ### Saving of Individuals as Templates Previously defined individuals can be saved as a template in the template database and then be shared among several projects and users. To save an existing individual as template: 1. Right mouse click on the respective individual in the **Building Block Explorer** 2. Select **Save as Template...** A message will appear confirming that the Individual was successfully saved in the template database. In case an individual with the same name already exists, a warning message will pop up and you have the following opportunities: * Override: This action will override the existing template. * Save as: You can save the individual under a different name. In this case, you will be asked to Rename the new template. * Cancel: This action will abort the saving process. ### Loading existing Individuals from Templates To load existing individuals from the template database: 1. Right mouse click on **Individuals** in the **Building Block Explorer** 2. Select **Load From Template...** 3. Select the desired individual from the user templates. In case an individual with the same name already exists in the project, a warning appears and you will have to **Rename** the individual that is to be loaded from template. 4. Click **OK** The selected individual will appear in the **Building Block Explorer** view. In addition, individuals can be directly loaded from the template database within a simulation (see [PK-Sim® - Simulations](/v12/working-with-pk-sim/pk-sim-documentation/pk-sim-simulations). ### Deleting Individuals To delete individuals from a project: 1. Right mouse click on the respective individual in the **Building Block Explorer** 2. Select **Delete...** 3. Confirm to delete the individual by clicking **Yes** {% hint style="warning" %} Please note that an individual that is used in any simulation of the project cannot be deleted. {% endhint %} # Creating Populations The properties of a population of individuals can be defined in the building block **Population** using the physiological database of PK-Sim®. * In case of the various **animal species**, no age-dependent distribution information for the anatomical and physiological parameters is included in the database so far. The algorithm generates random values in the \[Minimum Weight, Maximum Weight] interval defined by the user. The generation of a population is done by linear scaling of an average animal of the given species. This means that all organs always contribute to the same extent to the total body weight without taking into account differences related to, e.g., growth, or to different races of the respective animal species. * For **humans**, the population parameters database that comes with PK-Sim® includes information on the dependence of anatomical and physiological parameters relevant for PK-Sim® such as organ weights, blood flow rates, or tissue composition on age, gender, body weight, and body mass index, which have been collected in a comprehensive literature search. The algorithm generating a population then involves the following steps which are repeated until the target number of individuals is reached \[[97](/v12/references/references#97)]: A list of individuals is created with the proportion of males and females as defined by the user. For each individual, the algorithm tries to create a parameter set that fulfills the defined criteria (for more detailed description of the algorithm, see [Create Individual Algorithm](https://github.com/Open-Systems-Pharmacology/OSPSuite.Documentation/wiki/Create-Individual-Algorithm)): 1. An **Age** value is drawn from a uniform random number distribution in the **\[Minimum Age, Maximum Age]** interval. 2. For the **Age** assigned above, a **Height** value is randomly generated according to the height distribution defined in the database for the given **Age**. 3. The generation of the **Height** value might fail (i.e., the generated **Height** is not within the **\[Minimum Height, Maximum Height]** interval for **Age** drawn in 1.). In that case, the algorithm tries to perform steps 1. and 2. again. After a maximum of 100 attempts, it is assumed that no data is available in the database matching the user inputs, and an exception is thrown. 4. With **Age** and **Height** defined, the algorithm tries to create a random individual based on these values. The resulting body **Weight** should be in the **\[Minimum Weight, Maximum Weight]** interval. The organ volumes are randomly generated according to their organ volume distributions. If the resulting body weight, i.e., the sum of all organ volumes times their density, is in the specified **\[Minimum Weight, Maximum Weight]** interval, the individual is kept. If not, another individual is generated. This step is repeated up to 100 times. If then still no individual with a body weight within the **\[Minimum Weight, Maximum Weight]** interval is found, an exception is thrown. 5. The volume fractions of protein, water, and lipids of different organs are scaled according to the value defined in the database for the given age. 6. Finally, all parameters other than organ volumes for which distributions are available in the database (e.g., blood flow rates, hematocrit, etc.) are being randomly generated according to their distributions. 7. Finally, the algorithm checks that the **BMI** value corresponding to the generated **Height** - **Weight** combination is within the **\[Minimum BMI, Maximum BMI]** interval, which is either defined by the user, or queried from the database for the generated combination of age and weight. If so, the individual is added to the population. If not, the individual is discarded. The following figures show, as an example, the age dependency of the body weight, body height, and body mass index distributions for a certain population (white males). The data were taken from the NHANES study \[[82](/v12/references/references#82)]. ![Age dependence of the distribution in body weight for white males according to the NHANES study](/files/i8WyYzwBCjS1tsAfsatJ) ![Age dependence of the distribution in body height for white males according to the NHANES study](/files/oZdxVe6CWpsxHovSyKXU) ![Age dependence of the distribution in body mass index for white males according to the NHANES study](/files/76Z6wth2kisQ5pMcICMz) ## Definition of new Populations in PK- Sim® To create a new population, do one of the following: * Click on **Population** in the **Create** Group of the **Modeling & Simulation** Tab, or * Right mouse click on **Populations** in the **Building Block Explorer** and select "Add Population...", or * Use the shortcut **Ctrl+Alt+P** A dialog box will open where the properties of the population can be selected and/or defined. The **Create Population** dialog is subdivided into four tabs: **Demographics**, **Expression**, **User Defined Variability**, and **Distribution**. The population is initialized by giving it a **Name** in the respective input field. The name is used to identify the population when its properties are saved in the project and/or as a template. Moreover, the name is used for identification of the population in the simulation. ### Demographics tab In the first drop-down menu (**Based on individual**) you can specify an **Individual** that you previously defined in this project, specify the number of individuals in your population, and the percentage of females therein (only for humans). Further below, the **Population Parameters Ranges** can be set, i.e., the anthropometry of the individuals can be constrained, at the lower and/or upper ends of the ranges for the different properties. {% hint style="info" %} Please note that for animal populations the minimum and maximum body weight represent required input parameters. {% endhint %} {% hint style="warning" %} Technically, there is no restriction on the \[Minimum Weight, Maximum Weight] interval values. However, please note that the generation of an animal population simply results from linear scaling of the average animal species with the algorithm generating random values in the entire \[Minimum Weight, Maximum Weight] interval defined by the user. Hence, reasonable values should be chosen for this interval. {% endhint %} If no individual has been defined, you can: * Create a population based on an individual saved as a template: * Click on **Load** in the **Demographics** tab next to the **Based on individual** drop-down menu. * Select the individual from **User Templates** or the **Predefined Templates** * Click OK * If the name of the **Individual** loaded from template is already used in the project, a new name has to be defined. * Create a new individual which serves as a basis individual for the population: * Click on **Create** * Define the properties of the **Individual**. For details see [PK-Sim® - Creating Individuals](/v12/working-with-pk-sim/pk-sim-documentation/pk-sim-creating-individuals). If a human population is selected, the following parameters can be defined in the **Population Parameters Ranges** section: * Age: The age range in units of year(s), month(s), week(s), or day(s). The population database contains physiological information starting from preterm newborns to newborns (age "0") to 80 year old (100 years old for the European (ICRP, 2002) population) individuals. When a pediatric or an elderly population is simulated, only the age dependence of anatomical properties (size of the organs, blood flow rates, body composition, etc.) is considered. However, important pharmacokinetic differences in children and elderly can be caused by age-related differences in, for example, hepatic metabolic activity. These effects are automatically accounted for if the ontogeny of the elimination process has been defined in the **Expression** tab for the underlying **Individual**. To manually account for variations in elimination, use the **User Defined Variability** tab. * Height: The range of body heights of the individuals in units of cm or m. * Weight: The range of body weight of the individuals in units of kg or g. * BMI: The range of body mass index of the individuals in units of kg/m2. The BMI is a measure for the human fat content. It is given by the individual's height (H) and body weight (BW) according to the equation $$BMI = \frac{BW}{H^2}$$. If the population **Preterm** is selected, an additional age scale has to be taken into account. Preterm neonates are characterized by their gestational age (GA), which ranges between about 24 and 37 weeks, and their postnatal age (PNA, what we usually refer to as "Age"). In the model, preterm neonates catch up growth during their first two years of life so that there are no differences between a > 2 year old individual of the same race and gender born either preterm or term. {% hint style="info" %} Please note that for human populations, the minimum and maximum age (and gestational age in case of preterms) are required input parameters. For height, weight, and BMI, empty fields indicate the unconstrained state. The population database contains information on the age dependence of the body weight, body height, and BMI distributions of various human populations. {% endhint %} {% hint style="warning" %} The algorithm will only create virtual individuals with reasonable characteristics, i.e., that are in agreement with the database. It is, for example, impossible to create a 30 year old male with a height of 100 cm weighing 200 kg. If implausible combinations of weight, height, and BMI are given as constraints, PK-Sim® will not be able to create any individuals. {% endhint %} ### Expression tab In the tab **Expression**, proteins that should be expressed in the population can be defined. See section [PK-Sim® - Expression](/v12/working-with-pk-sim/pk-sim-documentation/pk-sim-expression-profile) for details on how to define the expression of proteins in an individual. ### User Defined Variability tab In the **User Defined Variability** tab, further physiological parameters can be varied, e.g., the gastrointestinal transit pattern, or transport or elimination via active processes. The parameters that are available for additional statistical variation are grouped based on their function and displayed, using the default settings, in a tree structure on the left hand side. Two parameter groups will always be available, namely the **Anatomy** and the **Physiology** parameter groups. The appearance of a third parameter group, the **Relative expressions**, is dependent on the processes defined in the underlying individual. To select a parameter in the tree view, do the following: 1. Click the plus sign (+) to open the respective tree view node 2. If present, click the next plus sign (+) to open the subsequent level of the tree view 3. Click on the desired parameter {% hint style="info" %} Use the **Filter** function above the tree view to find parameters more quickly. {% endhint %} Selected parameters can be added to the box on the right hand side by clicking **Add**. Accordingly, parameters can be removed from the box by clicking **Remove**. Parameters added to the box on the right hand side can be varied within the population simulation. For each parameter, a type of distribution and associated properties of the distribution can be chosen. Four types of distributions are available: * **Normal:** The parameter is normally (Gaussian-like) distributed. Mean and standard deviation must be given. Select the unit accordingly. * **LogNormal:** The parameter is log-normally distributed. Mean and geometric standard deviation must be given. Select the unit for the mean value accordingly. The standard deviation can be given as a (dimensionless) relative standard deviation. * **Uniform:** The parameter is evenly distributed between the minimum and maximum value. Select the unit accordingly. * **Constant:** The mean value is used for all individuals. Select the unit accordingly. {% hint style="info" %} Variability in clearance processes does not only originate from variability in the organ volume or blood flow to the eliminating organ, but also from variability in the expression levels of the protein involved. Therefore, variations of the reference concentration of the enzyme or transporter can be taken into account in addition to the variability that automatically results from the physiological variations. {% endhint %} {% hint style="info" %} In case of a virtual human population that contains individuals of different ages, PK-Sim® automatically takes into account the developmental changes in the specific glomerular filtration rate, i.e. in the glomerular filtration rate normalized to the volume of the kidney. However, like for active processes, additional variations of the specific glomerular filtration rate can be taken into account. {% endhint %} {% hint style="info" %} If for active processes, i.e., metabolizing enzymes, transport proteins, and protein binding partners, an ontogeny function was selected in the **Expression** tab of the **Individual** building block for the basis individual, relative activity as a function of age will be taken into account in the human population. {% endhint %} ### Distribution tab In the **Distribution** tab, the distribution of parameters that are variable in the virtual population are shown. To select a certain parameter, mark it in the parameter tree on the left hand side. Again, you can use the **Filter** function above the tree view to find parameters more quickly. The distribution of the parameter selected will be depicted in the adjacent graphic. The parameter distribution can either be displayed as absolute counts or as percentage. Choose either **Count** or **Percent** from the drop-down menu below the parameter tree. For human populations, the parameter distributions are color coded. In case of a virtual human population that contains male and female individuals, you can select from the first drop-down menu whether all, only male, or only female individuals should be displayed. If **All** is selected, the gender specific data can either be shown as neighboring bars or stacking bars. {% hint style="info" %} The distribution of any parameter can be copied as image via right mouse click on the graphic on the right hand side of the tab. {% endhint %} ## Setting or Editing Population Properties To set or edit the properties of an existing population: 1. Right mouse click on the respective population in the **Building Block Explorer** 2. Select **Edit...** or simply double click on the existing population in the **Building Block Explorer**. The window with the properties of the population will open. The properties defined in the **Additional Parameters** tab can be set or changed appropriately. Changes can be verified in the **Distribution** tab. After having set or changed the properties, the window can be closed by clicking on ![Image](/files/GeHXwqvOAa75Sa1A3G4d) which will save the changed population properties. {% hint style="info" %} Please note that the **Demographics** of an existing population, including all parameters automatically generated by the population algorithm, cannot be changed later on. In order to change the **Demographics**, please create a new population. {% endhint %} ## Exporting Populations to CSV Populations generated in PK-Sim® can be exported to a CSV format. The file, which can be opened in Excel®, contains all anatomical and physiological parameter values of each individual of the population. In order to export a population to csv: 1. Right mouse click on the respective population in the **Building Block Explorer** 2. Select **Export to CSV...** 3. Choose directory and enter file name 4. Click **Save**. The file is saved and can be subsequently opened with excel {% hint style="info" %} In addition to the export of the population parameters to CSV, population simulations can be exported to CSV via the Simulation Explorer. Then, the population parameters file (.CSV), the respective model file (.pkml), and an information file (.txt) with the relevant information about the PK-Sim® version number will be generated. For details please see (see [PK-Sim® - Importing and Exporting Project Data and Models](/v12/working-with-pk-sim/pk-sim-documentation/importing-exporting-project-data-models). {% endhint %} ## Extracting individuals You can extract specific individuals from a population and add them as standalone building blocks to the project for follow-up analyses. Individuals of interest can be identified within a population analysis (e.g. individuals associated with the percentiles displayed in a population Box-Whisker plot) To extract individuals from a population, right click on the respective population in the **Buildings Block Explorer** and select **Extract Individuals...**. ![Dialog for extracting individuals from a populatoin](/files/NZL322gFGdvjr7PLBzPM) ## Cloning of Populations To clone populations in the project: 1. Right mouse click on the respective population in the **Building Block Explorer** 2. Select **Clone...** 3. Set an alternative name for the population clone and enter a description, if desired 4. Confirm and close the window with **OK** ## Saving Populations as Templates Previously defined populations can be saved as templates and then be shared among several projects and users. To save an existing population as template: 1. Right mouse click on the respective population in the **Building Block Explorer** 2. Select **Save as Template...** In case a population with the same name already exists, a warning message will pop up and you have the following options: * Override: This action will override the existing template * Save as: You can save the population under a different name. In this case, you will be asked to Rename the new template. * Cancel: This action will abort the saving process ## Loading of existing Populations from Templates To load an existing population from the template database: 1. Right mouse click on **Populations** in the **Building Block Explorer** 2. Select **Load From Template...** 3. Select the desired population from the user templates In case a population with the same name already exists in the project, a warning message will pop up and you will have to **Rename** the population that is to be loaded from the template. 4. Click **OK** The selected population will appear in the **Building Block Explorer** view. In addition, populations can be directly loaded from the template database within a simulation (see [PK-Sim® - Simulations](/v12/working-with-pk-sim/pk-sim-documentation/pk-sim-simulations). ## Deleting Populations To delete a population from the project: 1. Right mouse click on the respective population in the **Building Block Explorer** 2. Select **Delete...** 3. Confirm to delete the population by clicking on **Yes** {% hint style="warning" %} Please note that a population that is used in any simulation of the project cannot be deleted. {% endhint %} # Compounds: Definition and Work Flows A **Compound** is a set of data that describes the properties of the substance whose behavior is to be simulated. These properties are defined within the building block **Compound**. For each project, several compounds may be defined. The compounds defined can be saved as templates and shared among several projects and users. ## Definition of new Compounds in PK- Sim® To create a new compound, do one of the following: * Click on **Compound** in the **Create** Group of the **Modeling** Tab, or * Right mouse click on **Compounds** in the **Building Block Explorer** and select **Add Compound...**, or * Use the short cut **Ctrl+Alt+C**. A dialog will open, where the properties of the compound can be defined. The compound is initialized by giving it a **Name** in the respective input field. The properties of the compound can then be set or changed: ![The Create Compound dialog. Here, the basic physico-chemical properties of diclofenac are shown.](/files/RVlTozZJ7dgQ9oAPWELJ) The **Create Compound** window is subdivided into three tabs: **Basic Physico-chemistry**, **ADME Properties**, and **Advanced Properties**. ### Basic Physico-Chemistry tab The basic physico-chemical properties of a compound are specified in the **Basic Physico-chemistry** tab. Most of the drug properties can have multiple values, e.g., coming from differed sources, determined using various methods or assays. During the simulation creation, you can choose one value for each property. #### To Enter an additional value: 1. Click **Add** at the end of a row. 2. Enter the alternative name 3. If desired, enter a short description in the respective input field 4. Click **OK** #### To delete a value: 1. Click **Delete** 2. Click **Yes** If several alternative values have been defined, you can select a default one by enabling the check box "Default". When setting up the simulation, a value set as default will be selected first. The alternative values can still be selected, if desired. {% hint style="info" %} Please note that a value set as default cannot be deleted. In order to delete the value, define another default value. {% endhint %} #### **Is small molecule** This checkbox defines whether the compound is a small molecule or a large molecule such as a protein. If not selected (i.e., the compound is treated as a large molecule), the permeability for passive diffusion into blood cells and into the intracellular space of the organs as well as the intestinal permeability are set to zero, as it is assumed that large molecules do not passively diffuse across the cell membranes. If the drug is a small molecule and is used in a **Model for proteins and large molecules**, the drug will not enter the endosomal space (see [Modeling of Proteins](/v12/mechanistic-modeling-of-pharmacokinetics-and-dynamics/modeling-concepts/modeling-concepts-modeling-of-proteins)). #### **Lipophilicity** {% hint style="info" %} Lipids in organ tissue are predominantly present in the form of phospholipid membranes. The best descriptor for lipophilicity is the partition coefficient between lipid membranes and water, as determined at physiological pH \[[43](/v12/references/references#43)]. This is called membrane affinity and the value to be entered is the logMA. It is recommended to use these membrane affinities as input parameters for PK-Sim®. With their use, it is very likely that specific organ and intestinal permeability coefficients are obtained that require no or only marginal adjustment. {% endhint %} {% hint style="info" %} If the membrane affinity is not available, other lipophilicity values (e.g., logP, clogP) can be used as surrogates. In this case the quality of the simulation results might be negatively affected. The membrane/water partition coefficient is predominantly affected by two contributions. A real lipophilicity, which describes the partitioning into the lipid core of a membrane, and the interaction between a molecule and the phospholipid head groups. Particularly for charged substances this can lead to large differences between membrane affinity and other lipophilicity descriptors. A common observation is that membrane affinity is much less pH dependent than, e.g., logD \[[21](/v12/references/references#21)]. For this reason, it is recommended to use a lipophilicity value for the neutral form, e.g., logP, as a replacement for membrane affinity if the latter is not available. A reasonable variation around the logP value should be allowed since this parameter is not 1:1 correlated with the membrane affinity. {% endhint %} #### **Fraction Unbound (plasma, reference value)** The free fraction of drug in plasma (fu) is a mixed parameter depending on both the species and the drug. Thus, it might be necessary to define several values for one compound, namely one for each species to be simulated. The respective species can be selected in the **Species** column from the drop-down menu. Later, during the create simulation process, the appropriate value can be selected from the alternatives defined here. In the uppermost row of this field, the user is asked to decide whether the drug is predominantly bound to either **albumin** or **alpha1-acid glycoprotein**. Depending on the predominant binding partner in plasma, the corresponding ontogeny function stored in PK-Sim® database will be used for scaling the plasma protein binding in children. If this information is not available or needed, you can also select **unknown** and the reference value selected in the simulation will be used irrespective of the age of the individual. In order to modify the fraction unbound as a function of disease please use the **Plasma protein scale factor** parameter defined in the **Individual building block**. With the help of this factor, the fraction of drug bound to either protein can be scaled up or down. The resulting fraction unbound parameter used in the simulation can be found in the list of parameters of the **Simulation** under the header **Distribution**. {% hint style="info" %} If the fraction unbound is known for one species, e.g., rat, but unknown for another one, e.g., dog, it is technically possible to simulate pharmacokinetics in the dog using the fraction unbound defined for the rat. In other words, PK-Sim® does not judge the consistence of the combination of the species and the fraction unbound. However, in this case the value should only be considered as a best guess and a reasonable variation around the fu values should be allowed. Similarly, for the scaling of pharmacokinetics from one species to another, make sure that not only the building block **Individual** is replaced but also mixed parameters such as fraction unbound in plasma and clearance pathways and/or expression data are changed appropriately. {% endhint %} #### **Molweight** In the first line the molecular weight (MW) of the substance is specified. For substances containing halogen atoms the number of these atoms should chosen from the drop down menu that can be opened next to the **Has Halogens** field. This input is used to calculate an *effective molecular weight*, which is needed to estimate the permeability values. It takes into account the small contribution of halogens to the molecular volume in relation to their weight. After the type and the number of halogens have been entered, the effective molecular weight is calculated automatically. {% hint style="info" %} Even though the property determining the diffusion coefficient is the molecular volume rather than the weight, only the latter is commonly available and has therefore been chosen as an easily accessible input parameter. However, in some cases this leads to inaccurate results, particularly since halogen atoms have a much smaller volume than what would be expected from their weight. Therefore, for substances containing such atoms, the “effective molecular weight” based on the following corrections is used (N = number of atoms, CF = correction factor): **Effective Molecular Weight** ![Image](/files/ttUuPvrAG3tMndPJNq2t) with CF = 17 for fluorine, CF = 22 for chloride, CF = 62 for bromine, and CF = 98 for iodine (see \[[93](/v12/references/references#93)]). {% endhint %} #### **Compound type / pKa** The type of compound: neutral, base, or acid. In case the compound is a base or an acid choose either **Base** or **Acid** from the drop-down menu. You will then be able to specify the respective pKa(s). Up to three pKa values can be specified. {% hint style="info" %} pKa values always refer to the pKa value of the acidic form of the compound. The compound type defines whether the pKa value refers to the uncharged acid "HA" (= type acid; the compound is charged when it dissociates to H+ and A-) or to the conjugated acid of a base "BH+" (= type base; the compound is uncharged when it dissociates to H+ und B). In other words, the compound type always refers to the uncharged form of the molecule. {% endhint %} {% hint style="info" %} The pKa values are used for the calculation of pH-dependent changes in solubility in the gastrointestinal tract. Furthermore, when using the distribution model (see [Creating new simulations in PK-Sim®](/v12/working-with-pk-sim/pk-sim-documentation/pk-sim-simulations#creating-new-simulations-in-pk-sim)) of Rodgers and Rowland or the model of Schmitt, the compound type is a basic parameter for calculating the partition coefficients. It is furthermore used by the two charge-dependent methods of Schmitt to calculate the permeability of the barrier between interstitial and cellular space. {% endhint %} #### **Solubility** The solubility of the compound (in the intestine): The solubility can be specified together with the type of measurement or the medium used (first column, **Experiment**). The corresponding unit can be chosen from the drop-down menu in the second column (**Solubility at Ref-pH**). For charged compounds, the pH value at which the solubility of the compound was measured should be given in the third column (**Ref-pH**). In the fourth column, the **Solubility gain per charge** can be modified, which defines the factor by which the solubility increases with each ionization step. In order to calculate the charge of the molecule, the fraction of each microspecies is calculated according to the Henderson-Hasselbalch equation for a given pH. This is done across the entire pH-range such that the fractions are used to calculate the probability with which a molecule is in a certain ionization state. Based on this information, the **pH-dependent solubility** of molecules with one or more ionizable groups is calculated. By clicking on **Show Graph**, the pH-dependent solubility across the whole pH range calculated based on the experimental solubility at the defined pH is shown. For neutral compounds the input fields **Ref-pH** and **Solubility gain per charge** and the graph are irrelevant. {% hint style="info" %} In the simulation, the intestinal solubility can be displayed for each segment based on the inputs made here and the pH values in the gastro-intestinal tract of the individual used in the simulation. {% endhint %} {% hint style="info" %} The solubility of the compound is only needed for the oral administration route. Additionally, it can be taken into account if, e.g., a Noyes-Whitney dissolution is assumed for other routes of administration such as intramuscular or subcutaneous drug administration. However, for this purpose, the dissolution function has to be defined in MoBi®. {% endhint %} {% hint style="info" %} First estimates can be made using water solubility. However, especially for lipophilic compounds this value might underestimate the solubility in the intestine so that it is better to use a value obtained under bio-relevant conditions (e.g., in *Fasted State Simulated Intestinal Fluid*, FaSSIF). If different values are available for one compound (e.g., in FaSSIF and in *Fed State Simulated Intestinal Fluid*, FeSSIF), several alternative solubility values can specified and the appropriate value can then chosen in the **Simulation** creation step. {% endhint %} #### Intestinal solubility as table function of pH Intestinal solubility can also be defined as a linear interpolation of measured (pH, Solubility) data pairs. ![](/files/x7cnCrGOUvKRF4apz0SI) ==> ![](/files/TxAtC4ARRJVr0FG7laBf) ### ADME Properties tab After having defined the basic physico-chemical properties of the compound, processes known to be involved in its distribution and elimination can be specified in the **ADME** tab. The **ADME** tab is accessible either by clicking Next or by directly clicking on the respective tab in the **Create Compound** window. Five kinds of processes can be defined in the **ADME** tab depending on the type of interaction between the compound and the biological entity influencing the pharmacokinetics of the drug in vivo: * Absorption * Distribution * Metabolism * Transport & Excretion * Inhibition * Induction For each of these items one or more ADME processes can be defined in order to systematically collect all available information on absorption, degradation, transport, and binding processes from, e.g., in vitro assays and use this information to obtain specific kinetic rates used in the simulation. A general workflow for defining a specific process in *Protein Binding Partners*, *Metabolizing Enzymes*, *Total Hepatic Clearances*, *Transport Proteins*, *Renal Clearances*, and *Biliary Clearances* is as follows: * Right click on the biological process you want to add to (e.g. **Metabolizing Enzymes** in the **Metabolism** branch, **Renal Clearances** in the **Transport & Excretion** branch, …). * Click on the **Add …** command (e.g. **Add Metabolizing Enzyme …**). * Enter a name for the biological process you want to add. * Enter a name for the data source (e.g. in vitro assay, literature, laboratory results). * Select the process type from the list. * Enter the required input parameters (see tables below for an overview of the input parameters for each process type). * If physiological parameters are based on in vivo measurements, e.g. the intrinsic clearance, the respective species used in the experiment has to be selected. * Click **OK**. After definition of the required parameters the specific clearance or kinetic rate constant used in the simulation is automatically calculated taking into account the parameters listed under **Calculation parameters**. {% hint style="info" %} Specifying a value for **Specific clearance**, which is normally calculated automatically by PK-Sim®, will overwrite the original formula. This is indicated by the symbol . The formula can be reset by clicking on Image {% endhint %} After having defined the biological properties of the compound, you must link the specific processes to the enzymatic, transport, and binding settings defined for the selected individual/species in the Simulation. This is described in [Select relevant biological processes](/v12/working-with-pk-sim/pk-sim-documentation/pk-sim-simulations#select-relevant-biological-processes). In the following, an overview of the process types is given that can be defined for the different biological properties, including additional information on the required input parameters. #### Absorption **Calculation of Specific Intestinal Permeabilities** PK-Sim® calculates the transcellular specific permeability of the intestinal wall is from the physico-chemical properties of a compound. In addition to the calculated specific intestinal permeability, experimentally determined permeabilities, e.g., from Caco-2-cell permeability assays, can be used. However, due to the large inter-laboratory variability in Caco-2 permeations, a proper calibration of the measured in vitro values and the calculated in silico permeabilities for a defined set of compounds is necessary. If the experimentally determined values for the intestinal permeabilities are available and the customized calibration method has been implemented in PK-Sim®, this option is then available in the drop-down menu in the *Calculation methods* window. **Specific Intestinal Permeability** Similarly, the specific intestinal permeability, i.e., the surface area-normalized transcellular permeability of the innermost layer of the intestinal wall, is calculated from the drugs´ lipophilicity and effective molecular weight. The paracellular pathway has been shown to have no impact on the accuracy of prediction of the fraction dose absorbed in humans \[[79](/v12/references/references#79)] and is therefore not accounted for, i.e., the value for the paracellular specific permeability is not automatically calculated. However, the paracellular pathway can be included in the simulation, if desired. You will find the parameter **Intestinal permeability (paracellular)** in the simulation within the parameter group **Permeability**. In case that more than one lipophilicity value has been specified, all corresponding calculated permeability values are displayed in the drop down list that opens if you click on **Show Values**. Later, in the **Simulation**, you can select which lipophilicity value is to be used for the calculation of the specific intestinal permeability, or you can select the manually entered specific intestinal permeability. {% hint style="info" %} In contrast to the procedure for permeability of organ membranes, the relation between intestinal permeability and the molecular properties of the compound was generated using experimental fraction of dose absorbed values. It was optimized to provide the best prediction of total fraction absorbed (for details see \[[79](/v12/references/references#79)]). {% endhint %} {% hint style="info" %} In the simulation parameters, the calculated specific intestinal permeability (transcellular) cannot be modified under the compound properties of the simulation. The appropriate simulation parameter can be found under the tree header "permeability". Please note that if the (calculated or manually entered) intestinal permeability (transcellular) is modified in the simulation, the permeability between the intracellular and interstitial space within the mucosa (`P (intracellular -> interstitial)`) will also automatically be scaled by the same factor. Otherwise, a disproportion between in the permeability of the apical and basolateral side of the enterocytes could be produced, leading to an accumulation of drug in the enterocytes. Likewise, a factor between the calculated intestinal permeability (transcellular) and an optional manual entry will be calculated to scale the permeability of the basolateral side of the enterocytes (`P (intracellular -> interstitial)`) appropriately. {% endhint %} {% hint style="info" %} If experimental values for intestinal permeability are available, e.g., from Caco2-cell permeability assays, a calibration of these in vitro values has to be performed for a defined set of compounds before they can be used as input parameters. This is due to the high inter-laboratory variability in absolute permeability values. In this calibration, the fractions of dose absorbed of the set of substances are correlated with the measured permeabilities. For new compounds, the corresponding intestinal permeability used in PK- Sim® is automatically calculated based on the Caco2 permeability value input. If you require an expert calibration of a defined set of experimentally determined permeabilities derived from in vitro assays, please contact your PK-Sim® support (). {% endhint %} For acids and bases, the transcellular intestinal permeability can be calculated dynamically along the gastrointestinal tract based on local luminal pH and the compound’s pKa. This option can be turned on in the simulation by enabling the switch **Use pH- and pKa-dependent penalty factor for charged molecule fraction** in the parameter group **Permeability**. When this option is enabled, the calculated specific intestinal permeability is multiplied by a penalty factor that accounts for the fraction of neutral species at the local pH in each GI segment. By default, PK-Sim keeps this option disabled because the original intestinal permeability model (Pint) was calibrated without this penalty term and using membrane affinity data measured at approximately neutral pH; enabling the penalty factor in that framework degraded prediction quality for the underlying calibration set. This design choice and its background have been discussed within the OSP community and development team (see discussions in OSP Forum [issue #25](https://github.com/Open-Systems-Pharmacology/Forum/issues/25) and [discussion #1816](https://github.com/Open-Systems-Pharmacology/Forum/discussions/1816)). Conceptually, only the neutral species is expected to permeate the phospholipid membrane effectively, and the neutral fraction varies with pH. A physiological basis for accounting for this is described by Willmann et al. \[[173](/v12/references/references#173)], where GI absorption is driven by regional physiology and compound ionization. In practice, historical PK-Sim implementations used membrane affinity measured near pH 7.4 as a lipophilicity surrogate. Because those values (and logMA in general) show limited pH dependence, the pH effect on permeability was not explicitly applied in the default calibration. Subsequent internal evaluations indicated that simply turning on a uniform penalty for the charged fraction, on top of those neutral-pH-based inputs, could bias permeability downwards (sometimes up to an order of magnitude) and worsen predictions. **Recommendations** 1. Keep the penalty factor off when using permeability or membrane-affinity inputs that were derived or calibrated under neutral pH assumptions (default behavior), to remain consistent with the Pint calibration. 2. Consider enabling the penalty factor when permeability is intended to reflect pH-dependent lipophilicity (e.g., when using or estimating pH-dependent logD or a permeability input explicitly tied to the neutral fraction along the gut) so that the neutral-species limitation is respected regionally. 3. You can find the switch **Use pH- and pKa-dependent penalty factor for charged molecule fraction** in a simulation under the parameter group Permeability. Use it deliberately: enable it when your permeability input and modeling intent reflect pH-dependent neutral-species transport; keep it disabled to stay consistent with legacy neutral-pH–based calibration. {% hint style="info" %} This approach cannot be implemented in PK-Sim. You can export the simulation to MoBi and implement the pH-dependent lipophilicity there. {% endhint %} 4. As a more rigorous alternative, provide pH-dependent lipophilicity (logD) rather than pH-invariant membrane affinity as input and refit permeability accordingly. Expert guidance suggests distinguishing between membrane affinity and lipophilicity: for example, using logD of the neutral form for bases and approximately logD − 1 for acids as an approximation for membrane partitioning. This approach aligns better with the physiological rationale that permeability is driven by partitioning into the lipid core of membranes, which is inherently pH dependent (see Willmann et al., 2004). #### Distribution - Distribution calculation **Partition coefficient calculation methods** Two parameters determine the rate and extent of passive distribution in the body: steady state organ-plasma partition coefficients (PC) as well as permeability surface area (PxSA) products of each organ, also called Cellular Permeabilities (CP). The partition coefficients are calculated from the physico-chemical properties of the compound. **How are PC and CP predicted in PK-Sim®?** PBPK modeling requires many substance-specific parameters, which are usually unknown and rarely accessible directly. These include the organ/plasma partition coefficients, the permeability surface area products, and intrinsic clearances. The difficulty in gathering this type of data is one of the major reasons that prevented a more widespread use of PBPK-modeling in the past. PK-Sim® addresses and solves these issues by including several published and proprietary methods for calculation of PC and CP from physico-chemical data that are experimentally accessible and, in most cases, are frequently determined during the course of drug development. **How are organ/plasma partition coefficients deduced from physico-chemical parameters?** Organ/plasma partition coefficients are based on the concept of partition coefficients between drug binding tissue constituents and water. These include lipid/water and protein/water partition coefficients. Several similar concepts for utilizing such partition coefficients and the composition of organ tissue to calculate the organ/plasma partition coefficients have been published (see \[[53](/v12/references/references#53)] and \[[86](/v12/references/references#86)] for examples; an overview is given in \[[32](/v12/references/references#32)]). Even though the idea is very similar in all cases, the different methods deviate in the kind of parameters that they use. PK-Sim® implements five different methods to calculate the partition coefficients for the organs: i) The PK-Sim® standard model, which is described in more detail below, and the approaches developed by ii) Rodgers & Rowland, iii) Schmitt, iv) Poulin & Theil, and v) Berezhkovskiy. The mechanistic equations for the different models are found in the respective literature (\[[53](/v12/references/references#53)], \[[59](/v12/references/references#59)], \[[62](/v12/references/references#62)], \[[60](/v12/references/references#60)], \[[61](/v12/references/references#61)], \[[68](/v12/references/references#68)], \[[54](/v12/references/references#54)], \[[55](/v12/references/references#55)], \[[52](/v12/references/references#52)], \[[5](/v12/references/references#5)]). In the PK-Sim® standard model \[[96](/v12/references/references#96)] the partition coefficients are calculated using the following equation: *** ![Partition Coefficients](/files/xvMIrMYtvLthguYiRMWv) with ![Image](/files/a8HJrTbLrejcwKIFVLhk) = volume fraction of water, lipid and protein, ![Image](/files/ZQqswzWeVKZqCLs9YhaA) = lipid/water partition coefficient, ![Image](/files/grXaouyR9CCUvEEw4zwn) = protein/water partition coefficient, ![Image](/files/vamggispVLfdhOeLUuTN) = free fraction in plasma. *** Partition coefficients are derived from input data as follows: ![Image](/files/ZQqswzWeVKZqCLs9YhaA) The value entered as **Lipophilicity** is directly used. ![Image](/files/grXaouyR9CCUvEEw4zwn) Calculated from **Lipophilicity** using a correlation determined experimentally by measuring the unspecific binding to different tissue protein fraction of various organs for a large set of diverse compounds. Drug partitioning between plasma and red blood cells ($$K\_{rbc}$$) is calculated in analogous manner to ![Drug Partitioning](/files/PN9TJqSvdqIFKfBDymK5) The only exceptions are the **Schmitt model** that additionally takes into account the amount of acidic and neutral phospholipids as well as neutral lipids, and the **Rodgers & Rowland** model, if experimental data for blood-to-plasma concentration ratios (B:P) are available. The equation for the calculation of $$K\_{rbc}$$ in the Schmitt partition model is: ![Drug Partitioning Schmitt](/files/nWBPpGtt9T5odxvvdaEM) If a value for B:P is used in the Rodgers & Rowland model, $$K\_{rbc}$$ is calculated as follows: ![Drug Partitioning Rodgers & Rowland](/files/D7LaNehknLhee3x8p7pq) where HCT is the hematocrit and $$BP\_{ratio}$$ is the blood-to-plasma concentration ratio. No general rules have emerged to determine which distribution model is best suited based on the knowledge about the substance properties. However, some trends are contained within the different model foundations and assumptions as outlined below: | Partition coefficient calculation method | Description | | ---------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | PK-Sim® Standard (default) | The relevant compound parameters are lipophilicity and binding to plasma proteins. As lipophilicity measure, the membrane affinity (partition coefficient between water and an artificial membrane bilayer) is preferred in this model. The subcompartments of tissue and blood or plasma are assumed to consist of lipids, proteins, and water. Therefore the respective volume fractions as well as lipid/water ($$K\_{lipid}$$) and protein/ water ($$K\_{protein}$$) partition coefficients of the compound are considered. | | Rodgers & Rowland | In contrast to the previous model, this approach explicitly considers electrostatic interactions between ionized compounds (e.g. moderate-to-strong bases) and anionic phospholipids at physiological pH. It also considers interactions with intracellular neutral phospholipids and neutral lipids. Two additional input parameters are therefore necessary for the calculation of partition coefficients: the blood to plasma concentration ratio $$BP\_{ratio}$$, as a measure for electrostatic interactions of drugs with acidic phospholipids, and the vegetable oil-water partition coefficient ($$D\_{vo:w}$$) which is a better surrogate than the octanol-water partition coefficient ($$P\_{o:w}$$) for neutral lipids \[[59](/v12/references/references#59)], \[[62](/v12/references/references#62)], \[[60](/v12/references/references#60)], \[[61](/v12/references/references#61)]. | | Schmitt | This approach offers a universally applicable method to calculate organ-plasma partition coefficients under explicit consideration of electrostatic interactions between charged molecules at physiological pH and acidic phospholipids. pH differences between different subcompartments are taken into account, which leads to different amounts of dissociated and undissociated weak acids and bases. In contrast to the Poulin & Theil model the lipid subcompartment is assumed to consist of neutral lipids, neutral phospholipids and acidic phospholipids in order to better describe partitioning into biological membranes – especially of charged drugs. For each of these membrane constituents fractional volumes based on experimental literature data were used 68. | | Poulin & Theil | The approach developed by Poulin and Theil considers the cell lipid subcompartment as mainly consisting of phospholipids with a lipophilicity-hydrophobicity behavior similar to a mixture of 30 % neutral lipids and 70 % water. Organ-plasma partition coefficients are then calculated using the volume fractions of the aqueous ($$F\_w$$) and organic subcompartments ($$F\_{neutral\ lipid}$$ and $$F\_{phospholipid}$$) of the respective organ and plasma for this distribution model (select the combobox "advanced" in Individual --> Anatomy & Physiology and go to Physiology --> Tissue and body fluid physiology --> Tissue composition). For adipose tissue, vegetable oil-water partition coefficients ($$D\_{vo:w}$$) are used as lipophilicity measures, whereas octanol- water partition coefficients ($$P\_{o:w}$$) are used for non-adipose tissue \[[53](/v12/references/references#53)], \[[54](/v12/references/references#54)], \[[55](/v12/references/references#55)], \[[52](/v12/references/references#52)]. | | Berezhkovskiy | The assumptions made to describe drug partitioning into biological membranes as well as the input parameters correspond to those made in the Poulin & Theil model. However, peripheral drug elimination as well as drug exchange between compartments are considered, which leads to a modified version of the equation presented by Poulin and Theil \[[5](/v12/references/references#5)]. | **Cellular permeability calculation methods** The rates of permeation across the cell membranes (interstitial-cell barrier) depend on the permeability surface area (PxSA) products of each organ. The permeability values (the part of the PxSA-products that is substance-dependent) are proportional to the permeability of a phospholipid bilayer for the simulated substance. They are calculated from the physico-chemical data of the compound currently active in the simulation. **How are permeability surface-area (PxSA) products predicted in PK-Sim®?** As a first approximation it can be assumed that all mammalian lipid membranes have the same permeability for a given substance. Of course this it not strictly true, because permeability depends on the composition of a membrane; the types of phospholipids and the content of cholesterol influence the rates with which a substance passes through the membrane \[[24](/v12/references/references#24)] \[[9](/v12/references/references#9)]. However, within the accuracy with which it is possible to estimate permeability from compound properties, it is permissible to make this simplifying assumption. Under these presumptions the PxSA-products are composed out of a compound specific term (permeability) and a species or physiology specific term (surface area). Because it is difficult to determine PxSA-products or their two components explicitly, the calculation method incorporated into PK-Sim® is based on the following procedure \[[36](/v12/references/references#36)]: First, PxSA-products were previously determined by fitting simulations to experimental concentration-time curves for the different organs. Secondly, such pinned values are scaled by the organ volume to take the change of surface area, e.g. from species to species, into account. Furthermore, it is assumed that permeability is proportional to the partition coefficient and the diffusion coefficient, the latter of which depends on lipophilicity and molecular size for lipid membranes. This means, that permeability can be scaled with lipophilicity and molecular volume relative to given values. This is done in PK-Sim® using the values derived from the fit described above and dependencies which rely on published and proprietary knowledge. There are three different methods available in PK-Sim® to calculate the permeability parameters for the barriers between interstitial space and intracellular space which can be chosen from the drop-down menu: | Permeability parameters calculation method | Description | | ------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | PK-Sim® Standard (default) | With the method PK-Sim® Standard, the permeability parameters are calculated from the physico-chemical properties given in the Compound Data Window. The degree of dissociation of acids and bases is not taken into account. It is assumed that this value is the same in all organs and species and that differences originate only from size-dependent surface areas. | | Charge dependent Schmitt |

With this method, the degree of dissociation of acids and bases is taken into account assuming that the permeabilities for charged species are significantly smaller than for neutral species. The degree of dissociation is calculated from the pKa-values given for the Compound and the pH-values of the interstitial and intracellular spaces given. The permeabilities calculated with the method PK-Sim® Standard P0 are modified by a factor f(pKa- values, pH-value) accounting for the fractions of neutral/charged species:
Image
Since the pH-values of the interstitial and intracellular space differ for some organs, the permeability in the direction interstitial space -> intracellular space can differ from the permeability in the direction intracellular -> interstitial space.

| | Charge dependent Schmitt normalized PK-Sim® |

This method calculates the permeabilities in a similar way as dependent the method Charge Dependent Schmitt with the difference, that Schmitt the permeabilities are normalized to obtain the values calculated normalized to with the method PK-Sim® Standard:
Image
Thus, the permeability in the direction interstitial -> intracellular is the same as calculated with the method PK-Sim® Standard while the ratio of the permeabilities in the two directions is the same as calculated with the method Charge Dependent Schmitt.

| **Specific organ permeability** The specific organ permeability, i.e., the organ permeability normalized to the surface area, represents the part of the permeability times surface area (PxSA)- products that is substance-dependent and they are proportional to the permeability of a phospholipid bilayer for the simulated substance. They are calculated from the physico-chemical data of the compound, namely the lipophilicity and the effective molecular weight. If different lipophilicity values have been specified several permeability values based on these alternative values are displayed in the drop down list that opens if you click on **Show Values**. If available, further permeability values can be entered manually. You can later chose the lipophilicity value that is to be used in the **Simulation** from the values specified here. {% hint style="info" %} Because it is difficult to determine PxSA-products or their two components explicitly, the calculation method incorporated in PK- Sim® is based on the following procedure \[[36](/v12/references/references#36)]: First, PxSA-products were previously determined by fitting simulations to experimental concentration-time curves for the different organs. Second, such pinned values are scaled by the organ volume to take the change of surface area, e.g. from species to species, into account. Furthermore, it is assumed that permeability is proportional to the partition and diffusion coefficient, the latter of which depends on the lipophilicity and molecular size for lipid membranes. This means that permeability can be scaled with lipophilicity and molecular volume relative to given values. This is done in PK-Sim® using the values derived from the fit described above and dependencies which rely on published and proprietary knowledge. {% endhint %} **Distribution - Specific Binding** Distribution of a compound is also influenced by specific binding to proteins either in plasma, the interstitial, or the intracellular spaces. It is possible to define such specific protein binding processes in the **Specific Binding -> Protein Binding** section. Right click on the entry "Protein Binding Partners" and select **Add Protein Binding Partner**. Select any of the proteins as binding partner and define the source (the "Data source" field will be added to the name of the created process). | Process Type | Description | Necessary Input Parameter | | ---------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------- | | Specific Binding | If experimental data on binding of the compound to specific protein binding partners are available, these values also suit as input parameters. | ![Image](/files/wpDxQKByL6EffS8zJeLY) | {% hint style="info" %} Sometimes enzymes that catalyze a metabolic degradation process can also bind the compound at a binding site different to the catalytically active center. It is therefore possible to link an enzyme defined in the individual/species to both a metabolic and a binding process when setting up a simulation. {% endhint %} #### Metabolism Depending on the available experimental information you can either define process types in as **Metabolizing Enzymes** or as **Total Hepatic Clearance**. Please note that the calculations offered for metabolizing enzymes refer to the liver in case of intrinsic clearance processes and in all other cases to the organ in which the respective enzyme is expressed. Using this calculation sheet, input values will be transferred to specific clearance values which are then used in the simulation. The sheet is only meant to help the user with the calculations. However, processes defined here may also be applied to other organs given that relevant expression levels are appropriately defined in the individual. **Metabolizing Enzymes** The following process types can be defined in the **Metabolizing Enzymes** section: | Process Type | Description | Required Input Parameters | | -------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | Intrinsic clearance – First order |

A first order degradation process catalyzed by intracellular enzymes is defined in the liver. The input parameters are intrinsic clearance values which are either estimated or scaled from in vitro data. The specific clearance used in the simulation is obtained by scaling the intrinsic clearance value from liver cells to the whole organ using the following calculation parameters:

• Volume (liver) \[l]
• Fraction intracellular (liver)

|

• Intrinsic clearance (measured with liver cells or fitted) \[l/min]
• Volume(liver) \[l]
• Fraction intracellular (liver)

| | Intrinsic clearance – Michaelis-Menten |

A Michaelis-Menten type saturable kinetics process for intrinsic clearance. The input parameters are Km \[µmol/l] and Vmax \[µmol/l/min] (referring to the liver tissue, e.g., liver slices or perfused liver) which were either estimated or scaled from in vitro data.
The specific Vmax value used in the simulation (referring to the cellular volume) is scaled from the Vmax in liver tissue using the following calculation parameters:
• Fraction interstitial (liver)
• Fraction intracellular (liver)
The default value for Km is 1 μmol/l. Itmay be changed manually.

|

• Km \[µmol/l]
• Vmax \[µmol/l/min] (measured with liver tissue or fitted)
• Fraction interstitial (liver)
•Fraction intracellular (liver)

| | In vitro clearance – First order |

By explicitly defining specific clearance values referring to the cellular volume (either estimated or scaled from in vitro data) and the corresponding enzyme concentration a specific clearance value normalized to the enzyme concentration is calculated automatically.
The default value for enzyme concentration is 1 μmol/l. It may be changed manually.

|

• Enzyme concentration \[µmol/l]
• Specific clearance \[1/min] (measured with cellular in vitro system or fitted)

| | In vitro clearance – Michaelis-Menten |

You can also explicitly define specific Vmax values referring to the cellular volume (either estimated or scaled from in vitro data) to implement a Michaelis-Menten type saturable kinetics process. This value is then used to calculate kcat by normalizing the specific Vmax value to the respective enzyme concentration.
The default value for Km and the enzyme concentration is 1 μmol/l. It may be changed manually.

|

• Vmax \[µmol/l/min]
• Km \[µmol/l] (measured with cellular in vitro system or fitted)

| | In vitro clearance – Hill | Metabolic enzyme activity is described as saturable process displaying a cooperativity, which is characterized by the Hill equation. The corresponding kcat value is calculated from Vmax determined in an in vitro assay. |

• Enzyme concentration \[µmol/l]
• Vmax \[µmol/l/min]
• Km \[µmol/l]
• Hill coefficient

| | In vitro metabolic rate in the presence of recombinant CYPs/enzymes – First Order | Some in vitro assays use recombinant CYP enzymes to determine in vitro clearance values. These can be used as input for PK-Sim® after correction for the enzyme concentration in the assay when implementing a first order degradation process. Differences in intrinsic activity (per unit CYP)between rhCYP and human liver enzymes complicate the issue \[[63](/v12/references/references#63)], \[[56](/v12/references/references#56)]. | • In vitro clearance / concentration of recombinant enzyme \[µl/min/pmol rec. enzyme] | | In vitro metabolic rate in the presence of recombinant CYPs/enzymes – Michaelis-Menten | If Km and Vmax values for a saturable kinetics process were determined experimentally using recombinant CYP enzymes, Km can be directly used as for PK-Sim® where as Vmax has to be normalized to the enzyme concentration in the assay. Differences in intrinsic activity (per unit CYP) between rhCYP and human liver enzymes complicate the issue \[[63](/v12/references/references#63)], \[[56](/v12/references/references#56)]. |

• In vitro Vmax /concentration of the recombinant enzyme \[nmol/min/pmol rec. enzyme]
• Km \[µmol/l]

| | In vitro metabolic rate in the presence of liver microsomes – First Order | In vitro clearance values obtained from microsomal assays can be used as input parameters for definition of a first order metabolization process. If the clearance values are normalized to the amount of microsomal protein present in the assay they can be used without further modification.The in vitro clearance value is scaled to an in vivo specific clearance value using the content of CYP proteins in liver microsomes. The default value is 108 pmol/mg microsomal protein which is the CYP3A4 protein content in liver microsomes (see note under the table). Please change this value if other enzymes were defined. |

• In vitro clearance for liver microsomes \[µl/min/mg mic. protein]
• Content of CYP proteins in liver microsomes \[pmol/mg mic. protein] (e.g. \[63], \[64], or measured experimentally)

| | In vitro metabolic rate in the presence of liver microsomes – Michaelis-Menten |

For the definition of a saturable Michaelis-Menten like kinetics process in vitro Vmax values normalized to the enzyme concentration in the microsomal assay can be used as input parameter.
The in vitro Vmax value is then scaled to an in vivo Vmax value using the content of CYP proteins in liver microsomes. The default value is 108 pmol/mg microsomal protein which is the CYP3A4 protein content in liver microsomes (see note under the table). Please change this value if other enzymes were defined.

|

• In vitro Vmax for liver microsomes \[pmol/min/mg mic. protein]
• Content of CYP proteins in liver microsomes \[pmol/mg mic. protein] (e.g. \[63], \[64], or measured experimentally)
• Km \[µmol/l]

| {% hint style="info" %} For calculation of in vivo clearance or Vmax values from in vitro values obtained from microsomal assays, the content of the CYP enzyme defined as the process type has to be specified. The default value in PK-Sim® is 108 pmol/mg microsomal protein which is the CYP3A4 protein content in liver microsomes \[[63](/v12/references/references#63)]. CYP enzyme contents in liver microsomes from this reference are shown when you move the mouse over the parameter Content of CYP proteins in liver microsomes. If you have defined other than these CYP enzymes, please insert the corresponding value in PK-Sim®. {% endhint %} **Definition of a metabolite in an enzymatic process** A metabolite of a compound can be defined and used either as a "sink" or treated like any other compound. See [How to set up a parent/metabolite simulation](/v12/working-with-pk-sim/pk-sim-documentation/pk-sim-simulations#how-to-set-up-a-parentmetabolite-simulation) for details. **Total Hepatic Clearance** The following process types can be defined in the **Total Hepatic Clearance** section: | Process Type | Description | Necessary Input Parameter | | --------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Liver Plasma Clearance |

If you have experimental plasma clearance values you can use them by choosing this process type. The specific clearance used in the simulation is then automatically calculated on the basis of the following parameters:

• Body weight \[kg]
• Volume (liver) \[l]
• Hematocrit
• Blood flow rate (liver) \[l/min]
• Blood flow rate (portal vein) \[l/min]
• Fraction intracellular (liver)
• Fraction unbound (experiment)
• Lipophilicity
• Blood/Plasma concentration ratio
• Plasma clearance \[ml/min/kg]

The default value for fraction unbound (experiment) is 0.5 in PK-Sim®. Please change this parameter if you have experimental data for the fraction unbound in the experimental assay (not in plasma).

|

• Fraction unbound (experiment)
• Plasma clearance \[ml/min/kg]

All parameters listed in the left column (if not entered, default values as specified in the Compound building block for the given species are used)

| | In vitro hepatocytes – t1/2 |

You can use measured t1/2 values from hepatocyte assays. The specific clearance used in the simulation is then automatically calculated considering the following parameters:

• Number of cells/g liver tissue
• Number of cell/incubation
• Fraction intracellular (liver)
• Fraction unbound (assay)
• t1/2 (assay) \[min]

The default value for fraction unbound (assay) is 0.1 in PK-Sim®. Please change this parameter if you have experimental data for the fraction unbound.

|

<• Number of cell/incubation
• Fraction unbound (assay)
• t1/2 (assay) \[min]

| | In vitro hepatocytes – residual fraction |

If hepatocyte assay data with residual fractions are available, please specify these values in this process type. The specific clearance used in the simulation is then automatically calculated on the basis of the following parameters:

• Number of cells/g liver tissue
• Number of cell/incubation
• Fraction intracellular (liver)
• Fraction unbound (assay)
• Measuring time \[min]
• Residual fraction

The default value for fraction unbound (assay) is 0.1 in PK-Sim®. Please change this parameter if you have experimental data for the fraction unbound.

|

• Number of cell / incubation
• Fraction unbound (assay)
• Measuring time \[min]
• Residual fraction

| | In vitro liver microsomes – t1/2 |

t1/2 values from microsomal assays can be used as input parameters to calculate specific liver clearances. Scaling of the in vitro value is done using the following parameters:

• Microsomal protein mass/g liver \[mg/g]
• Amount of protein in the incubation \[mg/ml]
• Lipophilicity (experiment)
• Fraction intracellular (liver)
• Fraction unbound (assay)
• t1/2 (microsomal assay) \[min]

The value for fraction unbound (assay) is calculated in PK-Sim® using the lipophilicity of the compound and the amount of protein in incubation. Please change this parameter if you have experimental data for the fraction unbound.

|

• Amount protein/incubation \[mg/ml]
• Fraction unbound (assay)
• t1/2 (microsomal assay) \[min]

| | In vitro liver microsomes – residual fraction |

Residual fractions obtained from liver microsome assays may also serve as input parameters. The value for the specific liver clearance is then calculated using the following parameters:

• Microsomal protein mass/g liver \[mg/g]
• Amount protein/incubation \[mg/ml]
• Lipophilicity (experiment)
• Fraction intracellular (liver)
• Fraction unbound (assay)
• Measuring time \[min]
• Residual fraction \[%]

The value for fraction unbound (assay) is calculated in PK-Sim® using the lipophilicity of the compound and the amount of protein in incubation. Please change this parameter if you have experimental data for the fraction unbound.

|

• Amount protein/incubation \[mg/ml]
• Fraction unbound (assay)
• Measuring time \[min]
• Residual fraction

| {% hint style="info" %} Total hepatic clearance is a systemic process that does not have to be linked to properties defined in an individual/species when generating a simulation. {% endhint %} #### Transport & Excretion Drug transport across endothelial, epithelia, or cellular barriers is responsible for the distribution and renal or biliary elimination of a compound. Different experimental approaches are available either to determine rate constants or organ clearances. Depending on the experimental data available you can define different process types for your compound in the **Transport Proteins**, the **Renal Clearances**, or the **Biliary Clearance** section. **Transport Proteins** | Process Type | Description | Necessary Input Parameter | | -------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------ | | Intrinsic active transport - Michaelis-Menten |

A transporter-mediated transfer of a compound across a cellular membrane is described as saturable process following the Michaelis-Menten type kinetics. The specific Vmax value used in the simulation (referring to the cellular volume) is scaled from the Vmax in liver tissue using the following calculation parameters:

• Fraction interstitial (liver)
• Fraction intracellular (liver)

The default value for Km is 1 μmol/l. It may be manually changed.

|


• Km \[µmol/l]
• Vmax \[µmol/l/min]

| | Specific active transport - Michaelis-Menten | Here a Michaelis-Menten type saturable transport process is defined. The input parameters are Km and Vmax (either estimated or scaled from in vitro data). The kcat value used in the simulation is scaled from the input Vmax value by normalization to the transporter concentration. The default value for Km is 1 μmol/l. It may be manually changed. |

• Transporter concentration \[µmol/l]
• Vmax \[µmol/l/min]
• Km \[µmol/l]

| | Specific active transport - Hill | A transporter mediated transfer of a compound across a cellular membrane is described as saturable process displaying a cooperativity which is characterized by the Hill equation. The corresponding kcat value is calculated from a specific Vmax as input value. |

• Transporter concentration \[µmol/l]
• Vmax \[µmol/l/min]
• Km \[µmol/l]
• Hill coefficient

| | In vitro active transport (vesicular assay) - Michaelis-Menten | A transporter mediated transfer of a compound across a cellular membrane is described as saturable process following Michaelis-Menten type kinetics. The corresponding kcat value is calculated from a specific Vmax normalized to the amount of transporter as input value which was determined in a vesicular transport assay. |

• In vitro Vmax / transporter \[nmol/min/pmol transfer]
• Km \[µmol/l]

| **Renal Clearances** | Process Type | Description | Necessary Input Parameter | | ------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------- | | Kidney Plasma Clearance |

When choosing this process type, experimental values for kidney plasma clearance can be used as input parameters. The specific clearance used in the simulation is then automatically calculated on the basis of the following parameters:

• Body weight \[kg]
• Volume (kidney) \[l]
• Hematocrit
• Blood flow rate (kidney) \[l/min]
• Fraction unbound (experiment)
• Plasma clearance \[ml/min/kg]

The default value for fraction unbound (experiment) is 1 in PK-Sim®. Please change this parameter if you have experimental data for the fraction unbound.

|

• Plasma clearance \[ml/min/kg]
• Fraction unbound (experiment)

| | Glomerular Filtration | Filtration fractions are used in the case that the renal clearance differs from the GFR according to the properties of the individual. Please note that for small molecules this observation indicates that the compound is either actively reabsorbed or secreted, respectively. The GFR fraction can be used as a surrogate to compensate for active re-absorption (GFR fraction <1) or secretion (GFR fraction >1). The calculation of the resulting "GFR" is done when setting up the simulation. | • GFR fraction | | Tubular Secretion – First Order | For definition of a first order tubular secretion process you can use tubular secretion rates (either estimated or scaled from in vitro data). The specific tubular secretion rate is then calculated on the basis of the kidney volume. | • Tubular secretion \[l/min] | | Tubular Secretion – Michaelis-Menten | You can also define a saturable tubular secretion process by specifying Km and TSmax values (either estimated or scaled from in vitro data). The specific tubular secretion rate is then calculated taking into account the kidney volume. |

• TSmax \[µmol/min]
• Km \[µmol/l]

| {% hint style="info" %} Kidney Plasma Clearance is a systemic process that does not have to be linked to properties defined in an individual/species in a simulation. In the case of the Glomerular Filtration, the individual/ species-dependent GFR represents a default value defined in the Individual building block. {% endhint %} **Biliary Clearance** | Process Type | Description | Necessary Input Parameter | | ------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------- | | Biliary Plasma Clearance |

If you have experimental biliary plasma clearance data you can use them by choosing this process type. The specific clearance used in the simulation is then calculated automatically on the basis of the following parameters:

• Body weight \[kg]
• Volume (liver) \[l]
• Hematocrit
• Blood flow rate (liver) \[l/min]
• Blood flow rate (portal vein) \[l/min]
• Fraction intracellular (liver)
• Fraction unbound (experiment)
• Lipophilicity (experiment)
• Blood/Plasma concentration ratio
• Plasma clearance \[ml/min/kg]

The default value for fraction unbound (experiment) is 1 in PK-Sim®. Please change this parameter if you have experimental data for the fraction unbound.

The amount secreted as bile flow is subsequently split into two fractions: The fraction of hepatic bile that flows into the gallbladder for storage, and the fraction that flows straight into the duodenum.

|

• Plasma clearance \[ml/min/kg]
• Fraction unbound (experiment)

| {% hint style="info" %} Biliary clearance is a systemic process that does not have to be linked to properties defined for an individual/species when establishing a simulation. {% endhint %} ### Inhibition and induction Drugs may influence a broad variety of ADME processes that in turn will then affect the PK of the drug and possibly also other drugs. See section [PK-Sim® Compounds: Defining Inhibition/Induction Processes](/v12/working-with-pk-sim/pk-sim-documentation/pk-sim-compounds-defining-inhibition-induction-processes) for details on how to define inhibition and induction processes in PK-Sim®. ### Advanced Parameters tab Additional compound-related parameters can be defined in the **Advanced Parameters** that are needed in case the particle dissolution function (see [Formulations](/v12/working-with-pk-sim/pk-sim-documentation/pk-sim-formulations)) or the model for proteins and large molecules (see [Modeling of Proteins](/v12/mechanistic-modeling-of-pharmacokinetics-and-dynamics/modeling-concepts/modeling-concepts-modeling-of-proteins)) are used. In all other cases, the parameters defined in the **Advanced Parameters** tab will not be used and can be left unchanged. #### **Particle dissolution** The particle dissolution function can be used for the simulation of the dissolution process of spherical particles administered orally and represents a dissolution function of the Noyes-Whitney type that is based on particle size \[[102](/v12/references/references#102)]. The following parameters cane be specified: • How the precipitated drug is treated (either as Soluble or Insoluble) • The aqueous diffusion coefficient D • The density of the drug in its solid form • The maximum size of particles that dissolves immediately • Enable supersaturation or not. **Supersaturation** is the increase in the concentration of a solution beyond its saturation point. If activated, the effective concentration of the compound in the intestinal lumen can exceed its defined intestinal solubility. The default value of this option is 'disabled', meaning that supersaturation is inactivated. Further parameters such as the mean particle size and the particle size distribution, the number of bins, and the diffusion layer thickness are considered to be related to the formulation and thus can be defined in the Formulation Building Block (see [Formulations](/v12/working-with-pk-sim/pk-sim-documentation/pk-sim-formulations)). #### **Model for proteins and large molecules** Four drug-related parameters which are used in the model for proteins and large molecules can be defined in the **Advanced Parameters** tab, namely: * **Radius (solute)**: The hydrodynamic radius of the drug. The default value for the solute radius is estimated from the molecular weight defined in the **Basic Physico-chemistry** tab. * **Kd (FcRn) in endosomal space:** the dissociation constant for binding to FcRn in the acidic endosomal space. By default, this value is set to a very high value, implying no binding. * **Kd (FcRn) in plasma/interstitial:** the dissociation constant for binding to FcRn in plasma and the interstitial space (neutral environment). By default, this value is set to a very high value, implying no binding. For monoclonal antibodies, the binding to FcRn in neutral environment is generally very weak or not detectable. In this case, the high default value for Kd (FcRn) in plasma/interstitial space can be kept. * **kass (FcRn):** the association rate constant for binding to FcRn in both the acidic endosomal space and the plasma/interstitial space. The default value is a typical value for monoclonal antibodies and can usually be kept as is. After all information about the compound properties has been entered, the **Create Compound** window can be closed by clicking **OK** . The new compound will appear in the **Building Blocks Explorer** view. ## Setting or Changing Compound Properties To set or change the properties of an existing compound: 1. Right mouse click on the respective compound in the **Building Blocks Explorer** 2. Select **Edit...** or simply double click on the compound in the **Building Blocks Explorer**. A window with the three tabs **Basic Physico-chemistry**, **ADME Properties**, and **Advanced Parameters** will open. The properties can be set or changed appropriately. The changes can be saved by closing the window by clicking on ![Image](/files/GeHXwqvOAa75Sa1A3G4d). ## Cloning Compounds To clone a compound in the project: 1. Right mouse click on the respective compound in the **Building Blocks Explorer** 2. Select **Clone...** 3. Enter an alternative name for the compound clone and enter a description, if desired. 4. Confirm and close the window by clicking **OK** ## Saving Compounds as Templates For each project, several compounds can be defined. They can be saved as templates and then shared among several projects and users. To save an existing compound as template: 1. Right mouse click on the respective compound in the **Building Blocks Explorer** 2. Select **Save as Template...** In case a compound with the same name already exists, a warning appears and you have the following options: * Override: This action will override the existing template. * Save as: You can save the compound under a different name. In this case, you will be asked to Rename the new template. * Cancel: This action will abort the saving process. ## Loading Existing Compounds from Templates As mentioned before, the compounds defined in a project can be saved as templates and then be shared among several projects and users. To load an existing compound from the template database: 1. Right mouse click on **Compounds** in the **Building Blocks Explorer** 2. Select **Load From Template...** 3. Select the desired compound from the user templates In case a compound with the same name already exists in the project, a warning pops up and you will have to **Rename** the compound that is to be loaded from template. 4. Click **OK** The selected compound will appear in the **Building Block Explorer** view. Compounds can also be directly loaded from the template database within a simulation. ## Deleting Compounds To delete a compound from the project: 1. Right mouse click on the respective compound in the **Building Block Explorer** 2. Select **Delete...** 3. Confirm by clicking **Yes** {% hint style="warning" %} Please note that a compound that is used in any simulation of the project cannot be deleted. {% endhint %} # Compounds: Defining Inhibition/Induction Processes Drugs may influence a broad variety of ADME processes that in turn will then affect the PK of the drug and possibly also other drugs. A specific and very common case of this very generic description of a drug-drug-interaction (DDI) is the inhibition of a metabolizing enzyme or a transporter. Most metabolizing enzymes are highly expressed in the liver and, therefore, drug clearance and the first pass metabolisms will be affected. Inhibition of a transporter may change the rate of absorption of a drug or the amount absorbed of a drug. If an inhibited transporter is expressed in the kidney or liver, drug excretion will be altered. The interaction processes in PK-Sim® are defined in the **ADME** tab of a compound. ## Inhibition Processes To set up an inhibition of a protein by a compound, do the following: * Right mouse click on *Inhibition* in the **ADME** tab of the compound that acts as an inhibitor and select *Add Inhibition Process*. * Select the affected enzyme/transporter and specify the source for assuming this inhibition. * Specify the type of inhibition from the Process type list (competitive, uncompetitive, non-competitive, mixed, irreversible/mechanism-based inactivation). The interaction types are described in the next sections. Inhibition changes reaction rates and/or the kinetics of active transports or metabolization reactions by modifying the following reaction and/or transport parameters: * The Michaelis-Menten constant $$K\_m$$ and the turnover number $$kcat$$ for Michaelis-Menten kinetics * The Specific Clearance for first order kinetics In case of a *Michaelis-Menten* process, the reaction/transport rate **without inhibition** is given by: $$v=\frac{V\_{max}\times S}{K\_M+S}$$ with $$V\_{max} = kcat \times E$$ is maximum velocity where $$kcat$$ is the rate constant and $$E$$ is the amount of enzyme/transporter, and $$S$$ = free substrate concentration. In an inhibition scenario, both, the turnover number kcat and the Michaelis- Menten constant, are modified to new apparent values: $$v=\frac{V\_{max,app}\times S}{K\_{M,app}+S}$$ with $$V\_{max,app} = kcat,app \times E$$ apparent maximum velocity which is the product of apparent $$kcat$$ and $$E$$, the amount of enzyme/transporter, and $$S$$ = free substrate concentration. PK-Sim® calculates the apparent $$kcat$$ and apparent Michaelis-Menten constant for the specified inhibition scenario. In case of a simple setting with just one inhibitor per process, the equations are listed in the next section. If first order processes are inhibited, the specific clearances will be altered. The generic expression for a reversible linear, non saturable metabolism/transport process of first order is: $$ {\huge \mathrm{CL}*{\mathrm{int,app}} = \mathrm{CL}*{\mathrm{int}} \left/ \left( 1 + \sum\_{a=1}^{m} \frac{I\_a}{K\_{I,a}} + \sum\_{c=1}^{o} \frac{I\_c}{K\_{I,c}} + \sum\_{d=1}^{p} \frac{I\_d}{K\_{Ic,d}} \right) \right.} $$ If an inhibition is set up for an enzyme or transporter, all processes with the same name will be linked and affected by the inhibition. An autoinhibition cannot be set-up because measured Ki values will already be altered due to autoinhibition. ![Metabolism or transport processes that are specified for a compound can be selected for inhibition.](/files/FMXVujG6reMcqA8bIH20) ### Competitive inhibition - simple setting with one inhibitor In a competitive enzyme inhibition, the inhibitor binds reversibly to the enzyme and competes with the substrate for free enzyme. In case of a reversible inhibition, high substrate concentrations can overcome this inhibition. The apparent Michaelis-Menten constant increases while the apparent maximum reaction velocity remains unchanged. ![Schematic representation of a competitive inhibition](/files/wKcuZdbJEsNCKmXt2lo4) $$v=\frac{V\_{max}\times S}{K\_{M,app}+S}$$ with $$v$$ = reaction velocity, $$V\_{max}$$ = maximum reaction velocity, $$K\_{M,app}$$ = apparent Michaelis-Menten constant, and $$S$$ = free substrate concentration. $$K\_{M,app}$$ is calculated as follows: $$K\_{M,app} = K\_M \times (1+\frac{I}{K\_I})$$ with the variables defined above and $$K\_M$$ = Michaelis-Menten constant in absence of an inhibitor, $$I$$ = free inhibitor concentration, and $$K\_I$$ = dissociation constant of the enzyme-inhibitor complex. ### Uncompetitive inhibition - simple setting with one inhibitor In a uncompetitive enzyme inhibition, binding of the inhibitor to the enzyme requires prior binding of the substrate to the enzyme. Binding of the inhibitor to the enzyme-substrate complex is reversible. This kind of inhibition decreases the apparent Michaelis-Menten constant and the maximum reaction velocity. ![Schematic representation of a non-competitive inhibition.](/files/bGpKuOFkbxQvQzqGakP2) The reaction rate is described by the following equation: $$v=\frac{V\_{max,app}\times S}{K\_{M,app}+S}$$ with $$V\_{max,app}$$ = apparent maximum reaction velocity, $$K\_{M,app}$$ = apparent Michaelis-Menten constant, and $$S$$ = free substrate concentration. The apparent maximum reaction velocity is decreased depending on the concentration of the inhibitor, and its affinity to the enzyme-substrate complex. $$V\_{max,app} = \frac{V\_{max}}{1+\frac{I}{K\_I}}$$ with $$V\_{max}$$ = maximum reaction velocity, $$I$$ = free inhibitor concentration, and $$K\_I$$ = dissociation constant of the enzyme-substrate-inhibitor complex. The apparent Michaelis-Menten constant is defined as follows: $$K\_{M,app} = \frac{K\_M}{1+ \frac{I}{K\_I}}$$ with the variables as defined above. ### Mixed Inhibition : Simple Setting with One Inhibitor In a mixed inhibition, the inhibitor binds reversibly to the enzyme or the enzyme/substrate complex with different affinities (and different dissociation constants). The inhibitor binding site is different from the substrate binding site on the enzyme molecule. The apparent Michaelis-Menten constant is changed and the apparent maximum velocity is decreased. ![Schematic representation of a non-competitive inhibition.](/files/lRyH2kbm5kOqsLWblJuV) The reaction rate is described by the following equation: $$v=\frac{V\_{max,app}\times S}{K\_{M,app}+S}$$ with $$V\_{max,app}$$ = apparent maximum reaction velocity, $$K\_{M}$$ = Michaelis-Menten constant in the absence of the inhibitor, and $$S$$ = free substrate concentration. The apparent maximum velocity is calculated as follows: $$V\_{max,app} = \frac{V\_{max}}{1+\frac{I}{K\_{Iu}}}$$ with $$V\_{max}$$ = maximum reaction velocity, $$I$$ = free inhibitor concentration, and $$K\_{Iu}$$ = dissociation constant of the enzyme-substrate-inhibitor complex. The apparent Michaelis-Menten constant is calculated as follows: $$K\_{M,app} = \frac{1+\frac{I}{K\_{Ic}}}{1+\frac{I}{K\_{Iu}}}$$ with $$K\_{Ic}$$ = dissociation constant of the enzyme-inhibitor complex, $$K\_{Iu}$$ = dissociation constant of the enzyme-substrate-inhibitor complex, and $$I$$ = free inhibitor concentration. ### Non-Competitive Inhibition : Simple Setting with One Inhibitor The non-competitive inhibition is a special case of a mixed inhibition in which an inhibitor binds reversibly to the enzyme and/or to the enzyme/substrate complex with the same inhibition constant ($$K\_I = K\_{Iu}=K\_{Ic}$$). The reaction velocity is described by the same equation as in a mixed inhibition and the apparent maximum velocity is described by the same equation as in an uncompetitive inhibition. ### Irreversible Inhibition / Mechanism-Based Inactivation Principally, an irreversible inhibition is a time-dependent inhibition (TDI) in which recovery is only due to de novo protein, e.g. enzyme synthesis. Thus, the in vivo production and degradation of enzyme has to be taken into account by PK- Sim®. Turnover of any protein inherently is a function of both, protein synthesis (a zero-order process) and protein degradation (a first-order rate process). In view of the kinetic nature of these processes, the rate constant of degradation frequently is the sole determinant of the "steady-state" concentration of each protein as it oscillates between the basal and the induced/repressed state. The natural enzyme turnover in PK-Sim® is represented as shown below. ![Enzyme E turnover (dEcat/dt) at steady state.](/files/dh0Hhkb2iRDd14REkBvu) Initial enzyme concentration E0 and turnover rate constants kdeg are set to default values based on literature. The rate of inactivation follows a hyperpolic kinetic pattern. Generally, TDI has a slow onset, but potentially its effects are more profound than those of reversible inhibitions. The most prominent example of a practically irreversible inhibition is the inactivation of CYP-mediated reactions in the presence of NADPH. A common model for mechanism-based inactivation is illustrated below: ![Schematic representation of a enzyme inhibition by a mechanism-based enzyme inactivator](/files/fP8VICDS7y6AZMWX3R8M) According to Silvermann et al. \[[72](/v12/references/references#72)], a mechanism-based enzyme inactivator (MBEI) requires a step to convert the compound to the inactivating species (k2). This step, which is generally responsible for the observed time dependence of the enzyme inactivation, usually is irreversible and forms a new complex (EI') which can have two distinctive fates: * The EI' is a reactive species and forms a covalent complex with the enzyme (Einact) (k4). * The species generated is released from the enzyme as a product/metabolite P of the inactivator and the enzyme is again available as active enzyme (k3). The ratio of product release to inactivation is termed the partition ratio and represents the efficiency of the mechanism-based inactivator: the partition ratio is described by k3/k4. The two principal kinetic constants that are useful in describing mechanism-based inactivation are **kinact** (the maximum rate of inactivation) and **Kkinact\_half** (in literature also often referred to as KI, the concentration at which the inactivation rate is half-maximal). Based on the reaction scheme shown above and with the typical assumption of quasi steady-state, it can be shown that **kinact** is a complex mixture of k2, k3, and k4, while **Kkinact\_half** is a complex mixture of k1, k-1, k2, k3, and k4: ![kinact is the maximum rate of inactivation](/files/lNtlv5E2XHHZRDumuz3K) ![Kkinact\_half is the concentration at which the inactivation is half-maximal](/files/iQUlIE5s2DUzfxI3yqIW) The implementation in PK-Sim® of one mechanism-based inactivator follows the equation shown below: ![Enzyme E turnover (dEcat/dt) in the presence of one inhibitor I.](/files/9WpzKAG1EX5jrzB4J6aN) Note that irreversible inhibition in PK-Sim® also always includes reversible binding of the mechanism-based inactivator to the enzyme so that it also acts as a competitive inhibitor. This process is defined by its dissociation constant Ki. By default (assuming the mechanism-based model based on \[[72](/v12/references/references#72)]), Ki equals Kkinact\_half. The user may choose a different value if applicable. If more than one compound other than the mechanism-based inactivator competes for the binding at the enzyme, this can easily be implemented by specifying for the respective compound a reversible (e.g. competitive) inhibition process. This process automatically accounts for the so called **substrate protection of the enzyme**. An example where there is one substrate and one mechanism-based inactivator simultaneously competing for the binding site is illustrated below. ![Schematic representation of an enzyme (E) inhibition by a mechanism-based enzyme inactivator I in the presence of a substrate S. E converts I into a metabolite P and S into M, additionally the inactivator inactivates irreversibly the Enzyme.](/files/AoI7GdRaPYEIDBDXDBEx) This model could be represented in PK-Sim® as follows ![Simultaneous modeling of mechanism-based inactivation by the Inhibitor I, competitive inhibition by the Inhibitor I and substrate protection. Upper equation: enzyme turnover; lower equation: substrate depletion rate via the respective enzyme.](/files/Lcu1I3uyNmyVrMgsiG27) Note that substrate protection can only be modeled by specifying a reversible inhibition process for the substrate (enter a Ki value). {% hint style="info" %} Given the variability and uncertainty associated with experimental determination of enzyme turnover rates, a sensitivity analysis for the enzyme half life should be considered in the modeling approach. {% endhint %} {% hint style="info" %} Please note that for the mechanism-based inactivator no clearance process is defined via the inactivation process by default. In theory, for every inactivated enzyme molecule, also one inactivator molecule is cleared; this must be separately defined by the user in form of additional metabolization/excretion processes for the inhibitor. {% endhint %} ## Protein Induction Enzyme or transporter induction can occur as a result of either increased **de novo synthesis of protein** or (in very rare cases and currently not implemented in PK-Sim®) a decrease in degradation following protein stabilisation induction. Some examples of induction processes are: * CYPs 1A1, 1A2 and 1B1 induced by aryl hydrocarbon receptor (AHR) that is activated by binding of e.g. dioxin, benzoapyrene, omeprazole (in vitro), tobacco smoke * CYP3A induced primarily by pregnane X receptor (PXR) that is activated by binding of e.g. rifampicin, phenobarbital, nifedipine * Activation of the pregnane X receptor induces a number of Phase II enzymes involved in drug metabolism as well as numerous transporters Implementation of induction in PK-Sim® uses the following parameters: * Emax: maximum in vivo induction effect (Dimension: dimensionless) * EC50: concentration of the inducer to reach half the maximal in vivo induction effect (Dimension: concentration) In an induction, Emax ranges from 0 (= no induction) to infinity. A value of 1 means that the effect is twice the effect without induction. Modelling of suppressed de novo synthesis (suppression) (for example in some cytokines) is also possible with PKSim using the induction specification of a compound. In a suppression, Emax ranges from 0 (=no suppression) to -1 (full suppression, no synthesis anymore). If the reaction of the enzyme Ex and the substrate Sj follows a Michaelis-Menten kinetics, the rate of the enzyme Ex degradation/production and the substrate Sj degradation are given by: ## Multiple Inhibitors : Equations Used by PK-Sim® The enzyme turnover for Enzyme X in the presence of m competitive (CI), n uncompetitive (UI), o non-competitive (NI), p mixed-type inhibitors (MI), q mechanism-based enzyme inactivators/time dependent inactivators (TDI) and r inducers (IND) is given by: ![Enzyme Ex turnover (dEx/dt) at steady state in the presence of m competitive (CI), n uncompetitive (UI), o non-competitive (NI), p mixed-type inhibitors (MI), q mechanism-based enzyme inactivators/time dependent inactivators (TDI) and r inducers (IND).](/files/bYdVIUxbS4FOqo6zwmuc) If the reaction of the enzyme Ex and the substrate Sj follows a Michaelis-Menten kinetics, the rate of the substrate Sj degradation is given by: ![Substrate Sj degradation dSj/dt) at steady state in the presence of m competitive (CI), n uncompetitive (UI), o non-competitive (NI), p mixed-type inhibitors (MI), q mechanism-based enzyme inactivators/time dependent inactivators (TDI) and r inducers (IND).](/files/SVXJBdbd269K8qK5Niad) In the above equation, the substrate Sj may also be an inhibitor of all kind, e.g. CI, UI, NI, MI, TDI or IND. Similarly, if the reaction of the enzyme Ex and the substrate Sj follows a first order kinetics, the rate of the enzyme Ex degradation/production and the substrate Sj degradation are given by: ![Enzyme Ex turnover (dEx/dt) at steady state in the presence of m competitive (CI), n uncompetitive (UI), o non-competitive (NI), p mixed-type inhibitors (MI), q mechanism-based enzyme inactivators/time dependent inactivators (TDI) and r inducers (IND).](/files/FnYb6NX5MsV7wUyiFiES) ![Substrate Sj degradation dSj/dt) at steady state in the presence of m competitive (CI), n uncompetitive (UI), o non-competitive (NI), p mixed-type inhibitors (MI), q mechanism-based enzyme inactivators/time dependent inactivators (TDI) and r inducers (IND).](/files/y8zAKefxP5H4yVPwb0TB) In the above equation, the substrate Sj may also be an inhibitor of all kind, e.g. CI, UI, NI, MI, TDI or IND. Please note that * As for all other inhibition types, there is no reversible auto-inhibition (which means: if a compound is substrate and reversible inhibitor of the same enzyme, it does not appear in the Km\_interaction\_factor.) In the formula above it's done by excluding the substrate from the sum terms (a#j, b#j, etc.). * For mechanism-based inactivators auto-inhibition can be accounted for by specifying a specific clearance pathway via the affected enzyme. * Free (unbound) concentrations of all inhibitors are used (e.g. TDI\_u,l(t) means: unbound concentration of TDI\_l). --- [Next Page](/llms-full.txt/1)