1 Introduction

The code examples provide in 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 Expo 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 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 with the following subdirectories:
- data/source/ - Raw source data. This directory is empty because this Expo doesn’t demonstrate assembling a derived data set from source data.
- data/derived/ - Data sets derived in this Expo. See Data Preparation for examples of creating these.
- data/spec/ - Data specification YAML files. See Introduction to yspec for more details.
script/ - Analysis scripts including the .R and .Rmd files described in Project walkthrough page listing.
model/ - NONMEM® control files and model outputs. Typically there will be subdirectories for different parts of the analysis: this repo includes model/pk/.
deliv/ - Project deliverables with the following subdirectories:
- deliv/figure/ - Figures, typically pdf and png files. Many are created by the scripts described in EDA Figures or Model Diagnostics and Parameterized Reports for Model Diagnostics.
- deliv/table/ - Tables, typically as .tex or .pdf. Many are created by the scripts described in EDA Tables and Parameter Tables.
- deliv/report/ - LaTeX files for creating the final report. MetrumRG uses LaTeX for report writing, though this part of our process is not detailed in this Expo.

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.