In Open-Systems-Pharmacology/OSPSuite-R: R package to manipulate OSPSuite Models

``` {r, include = FALSE} knitr::opts_chunk$set( collapse = TRUE, comment = "#>", fig.path = "man/figures/README-", out.width = "100%" )

# OSPSuite R package

<!-- badges: start -->

[![Build Badge](https://img.shields.io/github/actions/workflow/status/Open-Systems-Pharmacology/OSPSuite-R/main-workflow.yaml?branch=main&label=Build)](https://github.com/Open-Systems-Pharmacology/OSPSuite-R/actions/workflows/main-workflow.yaml)
[![Codecov test coverage Badge](https://codecov.io/gh/Open-Systems-Pharmacology/OSPSuite-R/branch/main/graph/badge.svg)](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
install.packages("remotes")
remotes::install_github("Open-Systems-Pharmacology/OSPSuite-R@*release")

Get the latest development version with:

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.

Install CRAN dependencies

When installing from such files, the CRAN dependencies need to be installed manually first.

# 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. The other non-CRAN dependencies needed for OSPSuite-R also have to be downloaded and manually installed:

• {rSharp}
• {ospuite.utils}
• {tlf}

If you use RStudio IDE, 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.

# 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.

For development version, each time a pull request is merged, this github action 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.

Contribution

We encourage contribution to the Open Systems Pharmacology community. Before getting started please read the contribution guidelines. If you are contributing to the codebase, please be familiar with the R coding standards as well as the collaboration guide.

License

OSPSuite-R is released under the GPLv2 License.

All trademarks within this document belong to their legitimate owners.

Open-Systems-Pharmacology/OSPSuite-R documentation built on Feb. 14, 2025, 4:48 p.m.