Explanation for System Prerequisites • uqsa

Everything in this article should be already known to all users and cover basic interactions with an operating system in the context of modelling, scientific computing, and simulations. Read this only for troubleshooting purposes.

In this guide we explain these things in much more detail than will be necessary for most (you probably already know how to install things).

So here is the shortest version of what you need to do, assuming that you use debian or ubuntu:

# tl;dr:
sudo apt install gcc pkg-config libgsl-dev r-base

You already know which commands to run on your distribution, with the package manager it uses.

The package pkgconf on Alpine Linux is not the original pkg-config but provides the pkg-config command (no further action needed):

sudo apk add gcc gsl pkgconf R         # should suffice

The following material is the long explanation on a few example systems (it is impossible to list all of them).

Motivation

In this package, we frequently solve an ordinary differential equation model in the context of biological experiments. This can be done using deSolve, but we prefer to use the solvers from the GNU Scientific Library, GSL (the gsl_odeiv2 library). We have written an interface to these solvers (called rgsl). The user facing interface is designed around the idea of simulation experiments: a list of instructions that result in a model simulation, possibly with multiple calls to the ODE solver to obtain the final time-series.

This experiment oriented interface is more convenient in our context (and usually much faster than using deSolve). The GSL is a system level dependency, which R cannot install by itself, usually the admin of your machine can do this (on the cluster). If that is you (e.g. on your laptop) and you don’t have GSL yet, then it is usually a one or two line command to install it.

System Prerequisites

If you are using an apple device, then you need a package manager that macbooks don’t come pre-configured with. One such package-manager is homebrew (this is unofficial work funded by donations) - install it using the command pasted on the homebrew homepage. You are probably already using it or something very similar, but if not then please do.

WARNING: macOS will definitely mention xcode at some point, apple is really keen on this. We have absolutely nothing to do with xcode, neither does gcc, or pkg-config. The insistence of macOS to provide gcc only through xcode is despicable as they have no right to gate-keep any of these.

GNU Scientific Library and pkg-config

To compile C sources at all (with or without gsl) requires a c compiler. We also need system specific compiler options related to linking and the location where gsl is stored. These compiler options can look like this: -lgsl -lgslcblas -lm, but also more complex (this depends on your system) – in an HPC environment they will almost certainly be very different.

We use pkg-config to determine the right compiler options (or pkgconf, which does the same thing (but faster)); pkg-config is available for macOS, GNU Linux, Unix, and *BSD (even Windows, not that it helps).

Operating System	install gsl	install pkg-config
Debian and Ubuntu	`sudo apt install libgsl-dev`	`sudo apt install pkg-config`
Alpine Linux	`sudo apk add gsl`	`sudo apk add pkgconf`
GNU Guix	`guix install gsl`	`guix install pkg-config`
Arch Linux	`sudo pacman -S gsl`	`sudo pacman -S pkgconf`
Gentoo	`sudo emerge sci-libs/gsl`	`sudo emerge virtual/pkgconfig`
macOS	`brew install gsl`	`brew install pkg-config`

Once gsl and pkg-config are available on the system, the icpm-kth/rgsl package should compile nicely.

If you are in a normal user shell (not a root shell, su -), and not using guix (or NixOS), then the commands require sudo or doas in front of them to have the required system administration rights. GNU Guix and NIXOS have package managers that don’t require administration rights.

macOS and pkgconf

You can use pkgconf instead of pkg-config on macOS. However, it is possible that

brew install pkgconf

will not actually provide the pkg-config command (it may).

This is again not something that has anything to do with us. Everyone who wants to use pkg-config via pkgconf on macOS needs to consider these things.

Make sure that the literal command pkg-config is actually available after installation. If it is not, then you can make a symbolic link to pkgconf and make it available:

which pkg-config      # e.g.: /usr/bin/pkg-config

should print a path if that command is available (or nothing, then it isn’t). If which pkgconf prints a valid path (it should), then make a symlink to it:

cd ~/.local/bin
# make the link
ln -s `which pkgconf` pkg-config

For this to have the desired effect, ~/.local/bin needs to be in your PATH environment variable.

If it is, then pkg-config becomes available from any directory, even in non-interactive shells.

R itself

Availability of specific versions of R depend on the version of your OS, how up-to-date your package database is, etc.. Here is a quick list of the approximate command:

Operating System	install R
Alpine linux	`sudo apk add R`
Debian/Ubuntu	`sudo apt install r-base`
GNU Guix	`guix install r`
Arch	`sudo pacman -S r`
Gentoo	`emerge --ask dev-lang/R`

On MAC, please follow the instructions on the R-Studio web-site. Or install the version from homebrew. These two will almost certainly be different versions, with different locations for packages. It is probably better to use only one of them (R-Studio or brew R).

R packages

Your system’s package manager may have system-wide R packages, e.g.: ubuntu has r-cran-desolve, such that sudo apt install r-cran-desolve would install the deSolve package for all users of your machine. In HPC environments this is preferable as user accounts can have harsh quotas on file sizes and file numbers.

But, R packages can also be installed from within R (for individual users), but only to a location that is writable to you, typically in your $HOME diectory. Please ensure that .libPaths() returns at least one location that you have write access to (this – again – is true for everyone, has nothing to do with us).

.libPaths()

If this command doesn’t print a path that you can write to, then you can create a new directory (in your home), and make it known to R:

mkdir -p ~/R/library && echo "R_LIBS=~/R/library" >> ~/.Renviron

Now, you can install R packages from The Comprehensive R Archive Network cran and github:

install.packages("remotes")

Our packages are not on CRAN, and can be installed like this:

require(remotes)
install_github("icpm-kth/uqsa")

Installation of Companion packages

We have developed two companion packages:

rgsl
- solves ODEs with an interface organised around simulation experiments
- uses solvers from the GNU Scientific Library
- is used in most of our examples
SBtabVFGEN
- organises the storage and loading of models
- loads SBtab content from tsv, ods, and excel files
- creates vfgen, MOD, sbml, and format free ODE files
- also loads biological data contained in the SBtab files into R variables (lists of simulation experiment setups)

Both are optional, but recommended (our examples use them).

RGSL

This package solves ODE initial value problems, given as lists of simulation experiments, with sudden interventions (like activation, or a sudden signal).

remotes::install_github("icpm-kth/rgsl")       # requires gsl in your OS, see above

This can be replaced with the standard solvers in the deSolve package. In our examples, the solvers in deSolve are always slower.

SBtab Model Handling

This package loads a model written in the SBtab format, which is designed for models in systems biology, but much easier to read than SBML:

remotes::install_github("icpm-kth/SBtabVFGEN") # if you plan to use SBtab

This can be replaced, if you have a different method of model creation or want to write the model source files by hand (which is hard for large models).

Installation of UQSA

remotes::install_github("icpm-kth/uqsa")       # this package
library(uqsa)                                  # to load it

Examples in the Package

The package itself also includes example models, with a run script for each of them. We advise users to copy the run scripts either from the repository or the installed package and adapt them. The location of a run file can be found like this:

uqsa::uqsa_example("AKAP79",pat="^run.*R$")

or by browsing the folders on GitHub (inst/extdata/). Copy one of them and adapt it to your needs.