1 Introduction

The code examples associated with this Expo are available in a Github repository.

This page describes how to download or clone the repository (repo), the directory structure, and some of the tools to set up and manage the R packages used in the analysis.

This Expo demonstrates how to get started with the suite of tools that we use at Metrum Research Group to ensure traceable and reproducible pharmacometrics research. We proceed step-by-step through a population pharmacokinetic (pop PK) modeling and simulation (M&S) analysis. We chose this example to illustrate a functional workflow of these tools with an understanding that some standards (e.g., sample sizes, etc) are simplified relative to the complexities of many typical analyses.

For precursory or supplemental information, MetrumRG provides additional open-courseware. In particular, if this is your first population PK analysis using NONMEM®, we would encourage you to first explore our online training resources.

Note that the code provided in this Github repo may not work exactly as written on your system. The code was written and tested in a Metworx environment; minor modifications may be required to allow for differences in the setup of your modeling environment. If you believe that an error is included in any of the scripts, or would like help troubleshooting the code, you can post an issue to the Github repo by following the “Report an issue” link on the right sidebar.

2 Tools used

2.1 MetrumRG packages

Metrum Package Network (MPN) / pkgr Create and manage curated, reproducible R package environments.

2.2 CRAN packages

renv Reproducible environments for your R projects.

3 Browsing and downloading the code

All the code and data for this Expo is located in a Github repository. The Github web interface allows you to explore the code and data in the project from your web browser.

The entire repo can be downloaded by clicking the green Code dropdown and Download ZIP.

Users familiar with Git and Github can clone the repo and interact with it as they would any other Git project.

4 Repository structure

This Expo uses a subset of the same directory and file structure as all MetrumRG projects. The repo README briefly outlines the location of key datasets and scripts. Below we describe some of the top-level directories and files in the repo.

data/ - Data files. This Expo contains the following subdirectories:
- data/derived/ - Derived data sets and data specification YAML files, used in these example scripts and models. See Data Preparation for examples of creating data sets like these or Introduction to yspec for more details on the specifications.
- data/source/ - Example source data, primarily used in data-prep.Rmd and Data Preparation.
script/ - Example scripts demonstrating some of the code described in this Expo.
model/ - NONMEM® control files and model outputs. Typically there will be subdirectories for different parts of the analysis: this repo includes model/pk/.

5 Setting up your R environment

MetrumRG manages R packages and their dependencies on a project-by-project level. This means each project uses its own isolated package library. This accomplishes two objectives:

All the packages needed for a project are installed and with the package versions you expect.
The R environment can be easily reproduced later, by you or a collaborator, in order to reliably reproduce your analysis.

We do this using three tools: pkgr, MPN, and renv. To learn more about how and why this works well, find more information in the Metworx Knowledge Base here.

While we do recommend using this approach to manage your R environment, the code in this Expo will run without setting up your R environment in this way.

5.1 Install R packages with `pkgr`

You can easily install all R packages needed to run this analysis using pkgr. If you’re using Metworx, you’ll already have pkgr installed. If you’re not using Metworx, click here for installation instructions.

In your terminal (not your R console) navigate to the top-level of this project repository and run the following:

pkgr install

This will read the pkgr.yml file and begin installing the requested packages. (To learn more about the pkgr.yml configuration file, click here.) When pkgr finishes running, restart your R session and begin working.

There are numerous packages used in this Expo and installing them will take some time. If you are using Metworx, we recommend launching a Workflow with at least eight vCPUs on the head node. pkgr uses all available cores to install packages, so using eight or more cores improves efficiency.

Note that pkgr and renv are already set up in this repo, so you can get started by running the pkgr install command. To read more about how to use this approach in your own projects, click here.

5.2 Install `bbi`

If you plan to run code using bbr, you also need to install bbi (a command line utility that bbr uses “under the hood”). Once you have installed bbr and your other R packages, simply run the following in the R console of this project:

bbr::use_bbi()

This will install bbi inside the bin/ directory in this repo. The .Rprofile in the repo is configured to look for bbi there.

Note that if you plan to use bbr to execute NONMEM® models, and you’re not using Metworx, you’ll need to do some additional configuration to tell bbi where to find your NONEMEM® installation. See the bbi_init() section of bbr’s “Getting Started” vignette for more details.