Chapter 2 Installation

nlmixr can be installed and used on several platforms. Installation can range from easy to challenging, depending on the platform. We are in the process of streamlining this process, and any help or suggestions are greatly appreciated!

2.1 nlmixr

2.1.1 Windows installer

For those not interested in customized installation on Windows, we recommend you download a Windows installer for your platform from the following link

2.1.2 Installation on Windows

To replicate the environment for nlmixr development on Windows, you may need administrator rights. The following steps should be performed:

  1. Install R 3.4.1 (or later - we recommend 3.5.0, and will assume this in the rest of these instructions) from the R website.
  • For best results, we suggest you use C:\R\R-3.5.0, but you can also use the default location (C:\Program Files\R\R-3.5.0) as well, if really needed. If writing to C:\ is not allowed, another option could be to install to %AppData%, which is typically in C:\Users\userName\AppData\. Most users have write access to this location.
  • When installing on 64-bit Windows, it is best practice to include only the 64-bit version. If you include 32-bit files, some packages may not run correctly. Additionally, both the 32- and 64-bit binaries have to be compiled for every package. Similarly, if running on 32-bit Windows, install only the 32-bit version of R (and Python, and Rtools).
    • Using “Program Files” may lead to difficulties because paths with spaces are not always supported by all R packages and typically the “Program Files” directory is read-only, which has also been known to cause problems. We do not recommend this.
  1. Install the appropriate version of Rtools for Windows, currently version 3.4, from here.
  • This is an absolute requirement, since it includes C++ and related compilers not usually available under Windows. Further, alternative toolsets installed from other sources may not work correctly.
  • For best results, use the default location of C:\Rtools
    • RxODE, a required component of nlmixr, checks and sets up the path based on the following:
      1. Rtools is in the path (fastest and recommended option)
      2. Rtools was installed with information saved to the Windows registry, and RxODE can find the installation.
      3. Rtools is on a hard drive installed in either Rtools or RBuildTools
    • If you are on 64-bit windows, please do not install the R 3.3.x 32-bit toolchain. These files can interfere with some packages that compile binaries, with unpredictable consequences. Similarly, only install 32-bit Rtools on 32-bit versions of Windows.
  • Make sure the compilers have been added to the Windows PATH environment variable, or RxODE and nlmixr may not work (this should be done automatically during installation). Under Windows, this is not strictly necessary, rather RxODE finds the paths and sets them up if they are not in the path environment. However, it is good practice.
  1. Install a version of Python for Windows.
  • This is used for its symbolic algebra package SymPy.
  • A very robust Python distribution that includes SymPy and many packages that may be useful to the data scientist and/or pharmacometrician is Anaconda. Although very straightforward and easy to install, it is quite a large download and contains much more than you will need to run nlmixr. When installing, use the Python 3.6 version. During the installation, Anaconda provides the option of adding itself to the PATH environment variable, but advises against it; please do this anyway (despite the red warning).
  • Another option is to use official Python, although you will need to install SymPy separately if you go this route, which is sometimes not straightforward under Windows 10 owing to folder permissions (see here for a few workarounds). Nonetheless, see here for instructions for installation from source or using pip. Note that if you approach us for support, we are going to recommend that you use Anaconda.
  • Regardless of the option you choose, please use 64-bit Python for 64-bit Windows (or vice versa for 32-bit).
  • Once again, make sure Python has been added to the Windows PATH environment variable, or RxODE and nlmixr will not work, no matter what Anaconda might say.
  1. Install devtools.
  • This package is required to install packages from GitHub, amongst other things.
  • This can be done from a clean R session by install.packages("devtools").
  1. Load devtools using library(devtools).
  2. Install RxODE.
  • Currently the new version of RxODE is in the process of being uploaded to CRAN. nlmixr needs this newer version of RxODE to function correctly. To install this version, use the command: install_github("nlmixrdevelopment/RxODE").
  • Once installed, type RxODE::rxWinPythonSetup() to install the required package SnakeCharmR and to make sure Python and SymPy are working properly.
  • Restart your R session.
  • As a quick test, you can make sure that R and Python can communicate by typing the command library(SnakeCharmR). This will will display the version of python you are using.
  • Another test to make sure that SymPy is setup appropriately is to do library(RxODE) and rxSymPyVersion(). This will display the SymPy version.
  • To validate or test the installation of RxODE completely, you can type the following library(RxODE); rxTest() and it will run all of the unit tests in RxODE to make sure it is running correctly on your system. (Note that the testthat package is required for this, and it will take a long time.) For a short test use rxTest(FALSE).
  1. Install nlmixr.
  • Load devtools again using library(devtools)
  • Install nlmixr by running install_github("nlmixrdevelopment/nlmixr")

2.1.3 Installation on Linux

Instructions for Ubuntu-alike distributions are given here (specifically, Ubuntu 16.04 Xenial Xerus), but all current Linux distributions are supported, in principle.

  1. Install R 3.4.1 (or later - we recommend 3.5.0) from an appropriate repository (Ubuntu Xenial shown below, based on instructions provided here).
  • You will need administrator privileges (i.e. access to sudo). Provide your admin password when asked.
  • Add the official CRAN repository for Ubuntu: sudo apt-key adv --keyserver keyserver.ubuntu.com --recv-keys E298A3A825C0D65DFD57CBB651716619E084DAB9
  • Add the official CRAN repository for Ubuntu: sudo add-apt-repository 'deb [arch=amd64,i386] https://cran.rstudio.com/bin/linux/ubuntu xenial/'. If you aren’t using Ubuntu Xenial, change xenial to match your distribution’s codename.
  • Now refresh the package list using sudo apt-get update.
  • We can now install base R and required development libraries, and their dependencies: sudo apt-get install r-base r-base-dev libssl-dev
  1. Install Python dependencies.
  • Enter this: sudo apt-get install python-sympy python-pip python-setuptools python3-pip python-dev python3-dev.
  1. Install devtools and dependencies.
  • This package is required to install packages from Github, amongst other things.
  • Some Linux distributions don’t include build tools out of the box. To be safe, check this: sudo apt-get install build-essential
  • Install devtools from a clean R session by entering install.packages("devtools").
  1. In R, load devtools using library(devtools).
  2. Install RxODE.
  • Currently the new version of RxODE is in the process of being uploaded to CRAN. nlmixr needs this newer version of RxODE to function correctly. To install this version, use the command: install_github("nlmixrdevelopment/RxODE").
  • Install SnakeCharmR using install_github("nlmixrdevelopment/SnakeCharmR").
  • Restart your R session.
  • As a quick test, you can make sure that R and Python can communicate by typing the command library(SnakeCharmR). This will will display the version of python you are using.
  • Another test to make sure that SymPy is setup appropriately is to do library(RxODE) and rxSymPyVersion(). This will display the SymPy version.
  • To validate or test the installation of RxODE completely, you can type the following library(RxODE); rxTest() and it will run all of the unit tests in RxODE to make sure it is running correctly on your system. (Note that the testthat package is required for this, and it will take a long time.) For a short test use rxTest(FALSE).
  1. Install nlmixr.
  • This can be done by install_github("nlmixrdevelopment/nlmixr")

2.1.4 Installation on macOS

Instructions for macOS 10.12 Sierra are provided here. They should be broadly extensible to all recent releases of macOS.

The general logic is to first install any external software and then install the R packages.

  1. Check the Python version in the terminal: python –version. On maxOS the standard version is 2.7, which is used by nlmixr. If there are other versions of Python available, set the $PATH to the 2.7 version and/or remove other versions of Python, if possible (this step can be a challenge).
  2. Install R 3.4.1 (or later - we recommend 3.5.0, and will assume this in the rest of these instructions) from the R website.
  • Download and install the appropriate R package (e.g. R-3.5.0.pkg) from CRAN.
  1. Install Python dependencies.
  • Install pip from the macOS or RStudio terminal prompt: sudo easy_install pip.
  • Install sympy using pip: sudo -H pip install sympy.
  1. Install build tools.
  • Install Xcode from the App Store (see which version matches your MacOS if you do not want to upgrade to the latest OS).
  • Read the license by entering the following at the macOS terminal: sudo xcodebuild -license
  • Scroll through it all, reading it carefully, and type agree at the end. (If you don’t, you can’t use nlmixr or anything else that requires compilation on macOS. Don’t yell at us, yell at Apple.)
  • Install gfortran: download the appropriate macOS installer from here and run it. Another option is to run the installation for the approriate macOS version from the terminal by typing: brew cask install gfortran to automatically install the version of gfortran on macOS needed by R from the Terminal (Mac or RStudio). Another option is to use the Mac build tools, which are the Mac equivalent of Rtools. With R 3.5, this includes clang6, which has open mp support required for threaded/parallel RxODE solving.

Now install the required R packages:

  1. Install devtools and dependencies.
  • This package is required to install packages from GitHub, amongst other things.
  • Install devtools from a clean R session by entering install.packages("devtools").
  1. In R, load devtools using library(devtools).
  2. Install RxODE.
  • Currently the new version of RxODE is in the process of being uploaded to CRAN. nlmixr needs this newer version of RxODE to function correctly. To install this version, use the command: install_github("nlmixrdevelopment/RxODE") or use install.packages('RxODE').
  • Install SnakeCharmR using install_github("nlmixrdevelopment/SnakeCharmR").
  • Restart your R session.
    • As a quick test, you can make sure that R and Python can communicate by typing the command library(SnakeCharmR). This will will display the version of python you are using.
  • SnakeCharmR wants to install the Python package SymPy and the latest macOS version does not allow this (installation of packages cannot be done system wide and has to be done on user level, or install as Adminstrator which may allow to install system wide). To do this on user level, open the terminal (in macOS or RStudio) and type: pip install simpy --user (the user flag is important!).
  • Another test to make sure that SymPy is setup appropriately is to do library(RxODE) and rxSymPyVersion(). This will display the SymPy version.
  • To validate or test the installation of RxODE completely, you can type the following library(RxODE); rxTest() and it will run all of the unit tests in RxODE to make sure it is running correctly on your system. (Note that the testthat package is required for this, and it will take a long time.) For a short test use rxTest(FALSE).
  1. Install nlmixr.
  • This can be done by install_github("nlmixrdevelopment/nlmixr") or install.packages('nlmixr').

2.1.5 Installation via Docker

Docker is a tool designed to make it easier to create, deploy, and run applications by using so-called “containers”. Containers allow complex applications to be wrapped as packages, ensuring they will run on any computer or platform regardless of any customized settings that machine might have that could differ from the machine used for writing and testing the code (a little like virtual machines, but more lightweight and portable). This is very attractive in our case, since it allows all the complexity above to be sidestepped neatly, and in principle makes the results obtained more reproducible.

The first thing to do is install Docker. An installer is available for all major operating systems:

Make sure you read the prequisites, but for most modern systems it is sufficient to download and run the installer.

  1. Runnning the container

To run a docker container you should use a terminal window (or command prompt in Windows).

The first time a container is run, it will donwload all applicable files from the repository. This can take some time depending on your internet speed. After the first time, the container will be saved locally and the machine will start almost immediately.

It is usually necessary to have access to your local drive, and this can be done by adding an option (-v) in the docker command. In the following example the folder /Users/richard/Document on the host computer will be mounted to the docs folder in the /home/rstudio directory of the container:

docker run -v /Users/richard/Documents/:/home/rstudio/docs -d -p 8787:8787 nlmixr/nlmixr:1.0

The version above applies to Linux, but it’s easy to do in Windows as well, by making the appropriate adjustments in the “Shared Drives” tab of the Docker settings app (accessible by right-clicking the Docker whale icon in the Windows system tray). Note that you may need adjust your firewall settings to enable folder sharing, and that you’ll probably need administrator privileges.

Once the Docker container is running, you can go to a browser and go to the following URL:

localhost:8787

This will launch an RStudio Server instance hosted inside the container. If everything has gone correctly you will see an RStudio login screen. You can log in with username and password rstudio. If a local folder was mounted, you should be able to find this directly in the RStudio files pane.

Note: In certain cases the localhost is not recognized and the url should be 127.0.0.1:8787

Note: If you are using Docker Toolbox on Windows 7, use the Docker Machine IP instead of localhost. For example, http://192.168.99.100:8787/. To find the right IP address, the ipconfig command can be used from the Command Prompt.

Note: In general, most modern browsers will work with RStudio Server. However, there might be some problems when running shiny apps. Both Chrome and Safari have been tested and should work correctly.

  1. Stop the container

Once you are done, or you would want to start another instance of the container, you can close the browser window and from the terminal the following can be done to stop all containers:

docker kill $(docker ps -q)

Note: In case you want to stop a specific conatainer, you can list the running containers with docker container ls and close the specific container ID (e.g. docker container stop 1fa4ab2cf395).

Note: In Windows it might be necessary to stop the container using Powershell; otherwise, the container can be stopped using Task Manager or through the Docker GUI.

2.2 project management tool (shinyMixR)

A user-friendly tool was developed for nlmixr based on Shiny and shinydashboards, which facilitates a workflow around an nlmixr project.

This shinyMixR package provides a means to build a project-centric workflow around nlmixr from the R command line and from a streamlined Shiny application. This project tool was developed to enhance the usability and attractiveness of nlmixr, facilitating dynamic and interactive use in real-time for rapid model development. More on the use of ShinyMixR in Chapter 3.3.

To install the package, use:

devtools::install_github("richardhooijmaijers/shinyMixR")