Skip to content

Commit

Permalink
Update documentation (#1484)
Browse files Browse the repository at this point in the history 
* Make showtext a dependency (#1409)

* Update README
- use remotes for installation (#1474)
- update Linux installation instruction (#1451)
- Add development section
- improve format
- wrap Rmd
- knit

* 🤖 Update Core Files.

* Add link to PK-Sim installation
+ simplify internal links (relative)

* Fix PK-Sim spelling

* use osp github avatar as icon

* Improve formatting

---------

Co-authored-by: github-actions <41898282+github-actions[bot]@users.noreply.github.com>
  • Loading branch information
@Felixmil @github-actions
Felixmil and github-actions[bot] authored Sep 3, 2024
1 parent 73f0687 commit 5ffa766
Show file tree
Hide file tree
Showing 27 changed files with 350 additions and 383 deletions.
4 changes: 2 additions & 2 deletions DESCRIPTION
View file
Original file line number Diff line number Diff line change
Expand Up @@ -34,15 +34,15 @@ Imports:
data.table,
xml2,
openxlsx,
lifecycle
lifecycle,
showtext
Suggests:
pacman,
knitr,
rmarkdown,
testthat (>= 3.0.3),
vdiffr (>= 1.0.0),
withr,
showtext,
sysfonts,
devtools (>= 2.4.5)
Language: en-US
Expand Down
215 changes: 98 additions & 117 deletions README.Rmd
View file
Original file line number Diff line number Diff line change
Expand Up @@ -2,9 +2,7 @@
output: github_document
---

<!-- README.md is generated from README.Rmd. Please edit that file -->

```{r, include = FALSE}
``` {r, include = FALSE}
knitr::opts_chunk$set(
collapse = TRUE,
comment = "#>",
Expand All @@ -13,107 +11,94 @@ knitr::opts_chunk$set(
)
```

# OSPSuite-R
# OSPSuite R package

<!-- badges: start -->
[![](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](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)

[![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 simulating the simulations created in the Open Systems
Pharmacology Software tools PK-Sim and MoBi.
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)
- [Code of conduct](#code-of-conduct)
- [Contribution](#contribution)
- [Licence](#licence)
- [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](https://www.open-systems-pharmacology.org/OSPSuite-R/articles/ospsuite.html)
- [Loading a simulation and accessing
entities](https://www.open-systems-pharmacology.org/OSPSuite-R/articles/load-get.html)
- [Changing parameter and molecule start
values](https://www.open-systems-pharmacology.org/OSPSuite-R/articles/set-values.html)
- [Running a
simulation](https://www.open-systems-pharmacology.org/OSPSuite-R/articles/run-simulation.html)
- [Efficient
calculations](https://www.open-systems-pharmacology.org/OSPSuite-R/articles/efficient-calculations.html)
- [Creating
individuals](https://www.open-systems-pharmacology.org/OSPSuite-R/articles/create-individual.html)
- [Population
simulations](https://www.open-systems-pharmacology.org/OSPSuite-R/articles/create-run-population.html)
- [PK
Analysis](https://www.open-systems-pharmacology.org/OSPSuite-R/articles/pk-analysis.html)
- [Sensitivity
analysis](https://www.open-systems-pharmacology.org/OSPSuite-R/articles/sensitivity-analysis.html)
- [Table
parameters](https://www.open-systems-pharmacology.org/OSPSuite-R/articles/table-parameters.html)
- [Dimensions and
Units](https://www.open-systems-pharmacology.org/OSPSuite-R/articles/unit-conversion.html)
- [Working with data sets and import from
excel](https://www.open-systems-pharmacology.org/OSPSuite-R/articles/observed-data.html)
- [Working with `DataCombined`
class](https://www.open-systems-pharmacology.org/OSPSuite-R/articles/data-combined.html)
- [Visualizations with
`DataCombined`](https://www.open-systems-pharmacology.org/OSPSuite-R/articles/data-combined-plotting.html)
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
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.

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

## On Windows

### Pre-requisites
## Pre-requisites

The package requires additional software installations:
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)

- Latest Microsoft Visual C++ Redistributable for Visual Studio 2015, 2017, 2019 and 2022 available [here](https://support.microsoft.com/en-us/help/2977003/the-latest-supported-visual-c-downloads)
- .NET 8 runtime available [here](https://dotnet.microsoft.com/download/dotnet/8.0/runtime).
## From GitHub (recommended)

**NB**: These pre-requisites are already installed if the OSP Suite was installed before.

### From GitHub (recommended)

The latest released version of the package can be installed from GitHub
using the `{pak}` package. The code below will download and install
all the required dependencies.
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("pak")
pak::pak("Open-Systems-Pharmacology/OSPSuite-R@*release")
install.packages("remotes")
remotes::install_github("Open-Systems-Pharmacology/OSPSuite-R@*release")
```

Get the latest development version with:

```{r, eval=FALSE}
install.packages("pak")
pak::pak("Open-Systems-Pharmacology/OSPSuite-R")
install.packages("remotes")
remotes::install_github("Open-Systems-Pharmacology/OSPSuite-R")
```

### From package archive files
## 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).
Expand Down Expand Up @@ -158,96 +143,92 @@ OSPSuite-R binary archive can be downloaded from
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)
- [`ospsuite.utils`](https://github.com/Open-Systems-Pharmacology/OSPSuite.RUtils/releases/latest)
- [`tlf`](https://github.com/Open-Systems-Pharmacology/TLF-Library/releases/latest)
- [`{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
**NB**: The CRAN dependencies of `{rSharp}`, `{ospuite.utils}` and `{tlf}` were already
installed during the previous step.


```r
``` 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
# 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
# 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(pathToOSPSuite.zip, repos = NULL)
install.packages(pathTo_OSPSuite.zip, repos = NULL)

```

## On Linux
# Known issues

The **ospsuite** package has been tested under Linux distribution
**Ubuntu 22.04**. Installation
under Linux requires several prerequisites, the detailed instructions
can be found in the Wiki:
## Loading `ospsuite` might fail if your systems locale is not set to English

- [Setup OSPSuite-R on
Ubuntu](https://github.com/Open-Systems-Pharmacology/OSPSuite-R/wiki/Setup-ospsuite-R-on-Ubuntu)
- On Windows, set `Settings > Language > Administrative language settings > Current language for non-Unicode programs`
to `English (United States)` and reboot.

For other Linux distributions Docker containers can be used (Docker container
based on Ubuntu 22 is available under
<https://github.com/Open-Systems-Pharmacology/OSPSuite-R/releases>)
- On Linux, set the environment variable `LC_ALL` before starting R:

## Build from source
`export LC_ALL=en_US.UTF-8`

You can clone the GIT repository and build the package from source.
## Saving and loading the workspace in RStudio does not restore objects

### How to update the libraries?
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.

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

## Embeded binaries

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

## Loading `ospsuite` might fail if your systems locale is not set to English
Since `{ospsuite}` contains this binary files, it is considered as a binary
package and thus cannot be submitted to CRAN in this state.

-- 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:
## Versionning

```
export LC_ALL=en_US.UTF-8
```
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).

## Saving and loading the workspace in RStudio does not restore objects
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.

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.

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

Expand Down
Loading

0 comments on commit 5ffa766

Please sign in to comment.