/
load-get.Rmd
148 lines (110 loc) · 5.82 KB
/
load-get.Rmd
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
---
title: "Loading a simulation and accessing entities"
output: rmarkdown::html_vignette
vignette: >
%\VignetteIndexEntry{Loading a simulation and accessing entities}
%\VignetteEngine{knitr::rmarkdown}
%\VignetteEncoding{UTF-8}
---
```{r setup, include = FALSE}
knitr::opts_chunk$set(
collapse = TRUE,
comment = "#>",
fig.showtext = TRUE
)
```
## Loading a simulation
In general, every workflow starts with loading a simulation by calling the `loadSimulation()` function. The function receives the full path to the **\*.pkml** file format exported from PK-Sim or MoBi, and returns the corresponding simulation object.
```{r loadSim}
library(ospsuite)
simFilePath <- system.file("extdata", "Aciclovir.pkml", package = "ospsuite")
sim <- loadSimulation(simFilePath)
```
## Accessing entities of the model and their properties - the path concept
Once the simulation is loaded, it is possible to retrieve various entities of the model. The most important entities are **containers**, **molecules**, and **parameters**. The methods `getContainer`, `getMolecule`, and `getParameter` search for the respective entity with the given `path` located under a `container`. `path` is a string where the elements of the path (i.e., containers in the hierarchy of the simulation) are separated by `|`. `container` is an instance of the `Container`-class within the model structure the path is *relative* to. In most cases, `container` is the `Simulation` object created by calling `loadSimulation(pkmlSimulationFile)`.
```{r getEntities}
# Get the molecule Aciclovir located in kidney intracellular space
moleculeInKid <- getMolecule("Organism|Kidney|Intracellular|Aciclovir", sim)
print(moleculeInKid)
# Get the container "Liver"
livContainer <- getContainer("Organism|Liver", sim)
print(livContainer)
# Get the parameter volume of the liver interstitial space
# Note that the path used is relative to the liver container
livParam <- getParameter("Interstitial|Volume", livContainer)
print(livParam)
```
The functions `getAllContainersMatching()`, `getAllMoleculesMatching()`, and `getAllParametersMatching()` return a list of objects representing all entities whose paths match the generic paths provided in the list `paths` located under `container`. Generic paths are constructed by using the wildcard symbols `*` (exactly one occurrence of any element) or `**` (zero or more occurrences of any element).
```{r getAllEntitiesMatching}
# Get the parameter `Volume` of the intracellular space of all organs,
# with exactly one path element before `Intracellular`
volumeParams <- getAllParametersMatching("Organism|*|Intracellular|Volume", sim)
length(volumeParams)
# The PBPK model has 15 organs with an "Intracellular" sub-compartment
# Get the parameter `Volume` of the intracellular space of all organs,
# no matter how many sub-containers the organ has
volumeParams <- getAllParametersMatching("Organism|**|Intracellular|Volume", sim)
length(volumeParams)
# The list also includes parameters of organs like "Liver|Periportal",
# or the mucosal compartments of the intestine.
```
Note that the path `"Organism|Kidney|*|Intracellular|Volume"` will return no parameters in the standard models, as there are no sub-containers between `Kidney` and `Intracellular`.
In contrast, `"Organism|Kidney|**|Intracellular|Volume"` is a valid path.
The functions `getAllContainersMatching()`, `getAllMoleculesMatching()`, and `getAllParametersMatching()` can also be used to retrieve entities from multiple paths:
```{r getAllEntitiesMatching_multiplePaths}
# Get the molecule Aciclovir located in `Liver|Periportal|Intracellular` and `VenousBlood|Plasma`
molecules <- getAllMoleculesMatching(c(
"Organism|VenousBlood|Plasma|Aciclovir",
"Organism|Liver|Periportal|Intracellular|Aciclovir"
), sim)
print(molecules)
```
The entities possess various properties that can be accessed through their objects. The most important properties for a container are:
```{r containerProperties}
# Path of the container
livContainer$path
# Parent container
livContainer$parentContainer
```
The most important properties for a molecule are:
```{r moleculeProperties}
# Initial value of the molecule
moleculeInKid$value
# Dimension of the molecule. See section "Unit conversion" for more information.
moleculeInKid$dimension
# Is the initial value defined by a formula?
moleculeInKid$isFormula
# Type of the formula. CONSTANT if the value is defined by a constant.
moleculeInKid$formula
```
The most important properties for a parameter are:
```{r parameterProperties}
# Initial value of the parameter
livParam$value
# Dimension of the parameter. See section "Unit conversion" for more information.
livParam$dimension
# Base unit of the parameter. See section "Unit conversion" for more information.
livParam$unit
# Is the initial value defined by a formula?
livParam$isFormula
# Type of the formula. CONSTANT if the value is defined by a constant.
livParam$formula
```
## Loading simulation tree
A convenient way to traverse the simulation structure is given by the method `getSimulationTree`. The method generates a tree-like list of all paths within the simulation. Each element of the tree contains all the sub-containers of the element. The final elements are strings representing the path to the entity.
```{r simTree}
# Load simulation
simFilePath <- system.file("extdata", "Aciclovir.pkml", package = "ospsuite")
sim <- loadSimulation(simFilePath)
# Create simulation tree
simTree <- getSimulationTree(sim)
# Calling simTree would list all entities within the simulation
# (given how long this tree can be, we will skip it here, but you can try
# running the following command in your console)
# simTree
# Accessing the parameter "Organism|Weight"
simTree$Organism$Weight
# Getting all entities located under "Organism|Liver|Periportal|Intracellular"
entitiesList <- simTree$Organism$Liver$Periportal$Intracellular
entitiesList
```