-
Notifications
You must be signed in to change notification settings - Fork 13
/
Copy pathREADME.Rmd
237 lines (166 loc) · 8.81 KB
/
README.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
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
---
output: github_document
---
``` {r, include = FALSE}
knitr::opts_chunk$set(
collapse = TRUE,
comment = "#>",
fig.path = "man/figures/README-",
out.width = "100%"
)
```
# OSPSuite R package
<!-- badges: start -->
[](https://github.com/Open-Systems-Pharmacology/OSPSuite-R/actions/workflows/main-workflow.yaml)
[](https://app.codecov.io/gh/Open-Systems-Pharmacology/OSPSuite-R?branch=main)
<!-- badges: end -->
# Overview
The `{ospsuite}`R package provides the functionality of loading, manipulating,
and running the simulations created in the Open Systems Pharmacology Software
tools PK-Sim and MoBi.
- [Documentation](#documentation)
- [Installation](#installation)
- [Known issues](#known-issues)
- [Development](#development)
- [Code of conduct](#code-of-conduct)
- [Contribution](#contribution)
- [Licence](#licence)
# Documentation
If you are reading this on GitHub README, please refer to the [online
documentation](https://www.open-systems-pharmacology.org/OSPSuite-R/) for more
details on the package.
In particular, we would recommend that you read the articles in the following
order:
- [Get Started](articles/ospsuite.html)
- [Loading a simulation and accessing entities](articles/load-get.html)
- [Changing parameter and molecule start values](articles/set-values.html)
- [Running a simulation](articles/run-simulation.html)
- [Efficient calculations](articles/efficient-calculations.html)
- [Creating individuals](articles/create-individual.html)
- [Population simulations](articles/create-run-population.html)
- [PK Analysis](articles/pk-analysis.html)
- [Sensitivity analysis](articles/sensitivity-analysis.html)
- [Table parameters](articles/table-parameters.html)
- [Dimensions and Units](articles/unit-conversion.html)
- [Working with data sets and import from excel](articles/observed-data.html)
- [Working with `DataCombined` class](articles/data-combined.html)
- [Visualizations with `DataCombined`](articles/data-combined-plotting.html)
- [PK-Sim Installation](articles/PKSim-installation.html)
# Installation
The **ospsuite** package is compatible with R version 4.x.x and can be used on
[Windows](#on-windows) and [Linux (Ubuntu)](#on-linux) operating systems.
`ospsuite` is not available on CRAN and also depends on packages from the OSP
ecosystem that are not available on CRAN. Please follow the instructions below
to install the packages and all required dependencies.
## Pre-requisites
As `{ospsuite}` relies on `{rSharp}`, install its external dependencies (Visual
C++ Redistributable and .NET 8) by following these instructions:
- [For
Windows](https://github.com/Open-Systems-Pharmacology/rSharp?tab=readme-ov-file#prerequisites)
- [For
Linux](https://github.com/Open-Systems-Pharmacology/rSharp?tab=readme-ov-file#ubuntu)
## From GitHub (recommended)
The latest released version of the package can be installed from GitHub using
the `{remotes}` package. The code below will download and install all the
required dependencies.
```{r, eval=FALSE}
install.packages("remotes")
remotes::install_github("Open-Systems-Pharmacology/OSPSuite-R@*release")
```
Get the latest development version with:
```{r, eval=FALSE}
install.packages("remotes")
remotes::install_github("Open-Systems-Pharmacology/OSPSuite-R")
```
## From package archive files (Deprecated)
It is also possible to install manually from archive pre-built archive files provided
with the [release](https://github.com/Open-Systems-Pharmacology/OSPSuite-R/releases).
#### Install CRAN dependencies
When installing from such files, the CRAN dependencies need to be installed
manually first.
```{r, echo = FALSE, results="asis"}
# This code chunck gathers all Depends and Imports dependencies of **installed**
# versions of the packages and generate a string that is printed in the README.md
# file.
library(pacman)
non_cran_deps <- c("rSharp", "ospsuite.utils", "tlf", "ospsuite")
deps <- c()
for (non_cran_dep in non_cran_deps) {
package_deps <- p_depends(non_cran_dep, local = T, character.only = T)
deps <- sort(unique(c(deps, package_deps$Depends, package_deps$Imports)))
}
deps <- deps[!deps %in% c("methods", non_cran_deps)]
dep_install <- paste('install.packages("', deps, '")', sep = "", collapse = "\n")
cat("```r \n")
cat("# Install dependencies (e.g. R6) which are on CRAN\n")
cat(dep_install)
cat("\n``` \n")
```
#### Install non-CRAN dependencies
Each of the pre-built released packages are available as a a binary `*.zip`.
OSPSuite-R binary archive can be downloaded from
[here](https://github.com/Open-Systems-Pharmacology/OSPSuite-R/releases). The
other non-CRAN dependencies needed for OSPSuite-R also have to be downloaded and
manually installed:
- [`{rSharp}`](https://github.com/Open-Systems-Pharmacology/rSharp/releases/latest)
- [`{ospuite.utils}`](https://github.com/Open-Systems-Pharmacology/OSPSuite.RUtils/releases/latest)
- [`{tlf}`](https://github.com/Open-Systems-Pharmacology/TLF-Library/releases/latest)
If you use [RStudio IDE](https://www.rstudio.com/), you can use the *Install*
option in the *Packages* pane and select the option *Install from -\> Package
Archive File* to install a package from binary `*.zip` files.
**NB**: The CRAN dependencies of `{rSharp}`, `{ospuite.utils}` and `{tlf}` were already
installed during the previous step.
``` r
# Install `{rSharp}` from local file
# (`pathTo_rSharp.zip` here should be replaced with the actual path to the `.zip` file)
install.packages(pathTo_rSharp.zip, repos = NULL)
# Install `{ospsuite.utils}` from local file
# (`pathTo_ospsuite.utils.zip` here should be replaced with the actual path to the `.zip` file)
install.packages(pathTo_ospsuite.utils.zip, repos = NULL)
# Install `{tlf}` from local file
# (`pathTo_tlf.zip` here should be replaced with the actual path to the `.zip` file)
install.packages(pathTo_tlf.zip, repos = NULL)
# Install `{ospsuite}` from local file
# (`pathToOSPSuite.zip` here should be replaced with the actual path to the `.zip` file)
install.packages(pathTo_OSPSuite.zip, repos = NULL)
```
# Known issues
## Loading `ospsuite` might fail if your systems locale is not set to English
- On Windows, set `Settings > Language > Administrative language settings > Current language for non-Unicode programs`
to `English (United States)` and reboot.
- On Linux, set the environment variable `LC_ALL` before starting R:
`export LC_ALL=en_US.UTF-8`
## Saving and loading the workspace in RStudio does not restore objects
The ospsuite package uses the features implemented in PK-Sim and MoBi by
creating `.NET` objects (e.g. a simulation) and using them from R. These objects
cannot be saved as part of the workspace and reloaded on next start. Upon
restoring the workspace, the objects will be `NULL` and cannot be re-used.
# Development
## Embeded binaries
The `{ospsuite}` package requires some shared libraries to get access to PK-Sim
functionality. To get the latest libraries(**.dll** on Windows or **.so** on
Linux), run the script file `update_core_files.R` provided with this package.
Since `{ospsuite}` contains this binary files, it is considered as a binary
package and thus cannot be submitted to CRAN in this state.
## Versionning
The package follows the versioning process described in the [OSP R collaboration
guide](https://dev.open-systems-pharmacology.org/r-development-resources/collaboration_guide#releasing-versions).
For development version, each time a pull request is merged, [this github
action](https://github.com/Open-Systems-Pharmacology/OSPSuite-R/blob/73f0687bad4671430468c24d1038b45dd6e73b0d/.github/workflows/main-workflow.yaml#L11-L17)
automatically bumps the `.9000` version suffix by one.
# Code of Conduct
Everyone interacting in the Open Systems Pharmacology community (codebases,
issue trackers, chat rooms, mailing lists etc.) is expected to follow the Open
Systems Pharmacology [code of
conduct](https://github.com/Open-Systems-Pharmacology/Suite/blob/master/CODE_OF_CONDUCT.md).
# Contribution
We encourage contribution to the Open Systems Pharmacology community. Before
getting started please read the [contribution
guidelines](https://github.com/Open-Systems-Pharmacology/Suite/blob/master/CONTRIBUTING.md).
If you are contributing to the codebase, please be familiar with the [R coding
standards](https://dev.open-systems-pharmacology.org/r-development-resources/coding_standards_r)
as well as the [collaboration
guide](https://dev.open-systems-pharmacology.org/r-development-resources/collaboration_guide).
# License
OSPSuite-R is released under the [GPLv2 License](LICENSE).
All trademarks within this document belong to their legitimate owners.