Skip to contents

OSPSuite R package

Overview

The ospsuiteR package provides the functionality of loading, manipulating, and running the simulations created in the Open Systems Pharmacology Software tools PK-Sim and MoBi.

Documentation

For complete documentation, see the online documentation.

Essential Guides

Essential guides:

For advanced workflows:

Data handling and visualization:

Reference:

Installation

The ospsuite package requires R version 4.x.x and supports Windows and Linux (Ubuntu) operating systems.

ospsuite is not available on CRAN and depends on packages from the OSP ecosystem that are not available on CRAN. Follow the instructions below to install the package and all required dependencies.

Pre-requisites

The ospsuite package requires rSharp and its external dependencies (Visual C++ Redistributable and .NET 8). Install these dependencies using the following instructions:

Install the latest released version from GitHub using the remotes package. This installation method downloads and installs all required dependencies.

install.packages("remotes")
remotes::install_github("Open-Systems-Pharmacology/OSPSuite-R@*release")

To install the latest development version:

install.packages("remotes")
remotes::install_github("Open-Systems-Pharmacology/OSPSuite-R")

From package archive files (Deprecated)

Install manually from pre-built archive files available in the releases.

Install CRAN dependencies

Installing from archive files requires manual installation of CRAN dependencies first.

# Install dependencies (e.g. R6) which are on CRAN
install.packages("cli")
install.packages("crayon")
install.packages("data.table")
install.packages("dplyr")
install.packages("ggplot2")
install.packages("ggtext")
install.packages("glue")
install.packages("jsonlite")
install.packages("lifecycle")
install.packages("logger")
install.packages("openxlsx")
install.packages("patchwork")
install.packages("purrr")
install.packages("R6")
install.packages("readr")
install.packages("rlang")
install.packages("showtext")
install.packages("stringi")
install.packages("stringr")
install.packages("tidyr")
install.packages("xml2")

Install non-CRAN dependencies

Pre-built packages are available as binary files (.zip for Windows, .tar.gz for Linux) Download the OSPSuite-R binary archive from the releases page. Download and install these additional non-CRAN dependencies:

In RStudio IDE, use the Install option in the Packages pane and select Install from -> Package Archive File to install packages from binary files.

Note: CRAN dependencies for rSharp, {ospuite.utils}, and tlf were installed in the previous step.

# Install rSharp from local file
# Replace pathTo_rSharp.zip with the actual path to the .zip file (or to the .tar.gz file on Linux)
install.packages(pathTo_rSharp.zip, repos = NULL)

# Install ospsuite.utils from local file
# Replace pathTo_ospsuite.utils.zip with the actual path to the .zip file (or to the .tar.gz file on Linux)
install.packages(pathTo_ospsuite.utils.zip, repos = NULL)

# Install tlf from local file
# Replace pathTo_tlf.zip with the actual path to the .zip file (or to the .tar.gz file on Linux)
install.packages(pathTo_tlf.zip, repos = NULL)

# Install ospsuite from local file
# Replace pathToOSPSuite.zip with the actual path to the .zip file (or to the .tar.gz file on Linux)
install.packages(pathTo_OSPSuite.zip, repos = NULL)

Known issues

Loading ospsuite might fail if the system 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 to ~/.bashrc before starting R:

    export LC_ALL=en_US.UTF-8

  • add the path to the lib subfolder of installed ospsuite package to LD_LIBRARY_PATH export LD_LIBRARY_PATH=/usr/local/lib/R/site-library/ospsuite/lib/:$LD_LIBRARY_PATH

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

Embedded binaries

The ospsuite package requires shared libraries (binary files) to access PK-Sim and MoBi functionalities.

Note: Because ospsuite contains binary files, it is classified as a binary package and cannot be submitted to CRAN.

Updating embedded binaries

The embedded binaries are built from NuGet packages specified in the DependencyManager project. To update the binaries to a new version:

  1. Open shared/DependencyManager/src/DependencyManager.csproj.
  2. Update the Version attribute in the PackageReference elements to the desired version numbers.
  3. Commit and push the changes to a branch.
  4. The GitHub Actions workflow defined in .github/workflows/build-libraries.yaml automatically:
    • Builds the DependencyManager project, which downloads the specified NuGet packages
    • Extracts the required binary files and dependencies
    • Copies them to the inst/lib/ directory
    • Commits the updated binaries to the branch

No manual build steps are required. The workflow handles the entire process automatically when changes to the .csproj file are pushed.

Note: If the DependencyManager.csproj file is not modified, the build-libraries workflow step is automatically skipped.

Versioning

The package follows the versioning process described in the OSP R collaboration guide.

For development versions, this GitHub action automatically increments the .9000 version suffix when pull requests are merged.

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

Contributions to the Open Systems Pharmacology community are welcome. Before contributing, read the contribution guidelines. Code contributors should follow the R coding standards and collaboration guide.

License

OSPSuite-R is released under the GPLv2 License.

All trademarks within this document belong to their legitimate owners.