Building and Estimating the First Population PK Model

Write, fit, and interpret the first population PK model using nlmixr2.
Tip

Module goal: Move from structural PK simulation to the first estimated population PK model using nlmixr2.

Module Overview

In the previous module, we built structural PK intuition.

We learned how a one-compartment oral model connects:

Dose

↓

Absorption

↓

Central compartment

↓

Elimination

↓

Concentration-time profile

Now we begin formal population model estimation.

This module introduces the first complete nlmixr2 workflow:

  • writing a model function
  • defining initial estimates
  • adding random effects
  • adding residual error
  • fitting the model
  • reading the fit output
  • extracting predictions and residuals
  • interpreting model results

The goal is not to build the final best model yet.

The goal is to understand how a population PK model is specified, estimated, and interpreted in nlmixr2.

Learning Objectives

By the end of this module, you will be able to:

  • Write a basic nlmixr2 one-compartment oral PK model.
  • Explain the role of ini() and model() blocks.
  • Define fixed effects, random effects, and residual error in nlmixr2.
  • Fit a model using FOCEi.
  • Read key parts of the fitted model output.
  • Interpret typical parameter estimates.
  • Extract predictions and residuals.
  • Understand the difference between structural prediction, population prediction, and individual prediction.

Lessons in This Module

Lesson 1: Writing Your First nlmixr2 Model

This lesson introduces the structure of an nlmixr2 model function, including ini() and model() blocks.

Lesson 2: Running FOCEi Estimation

This lesson fits the first one-compartment oral population PK model to theo_sd using FOCEi.

Lesson 3: Reading the Fit Object

This lesson walks through the fitted model object and introduces the main output components.

Lesson 4: Understanding Parameter Estimates

This lesson interprets typical parameter estimates, interindividual variability, and residual error terms.

Lesson 5: Predictions and Residuals

This lesson extracts and interprets predictions, individual predictions, and residuals from the fitted model.

Software Used

This module introduces nlmixr2 for model estimation.

library(tidyverse)
library(nlmixr2)
library(nlmixr2data)

Supporting packages may be introduced later for diagnostics and visualization.

library(ggPMX)
library(nlmixr2plot)

We will keep diagnostics light in this module. A full diagnostic workflow comes in the next module.

Dataset Used

We continue using:

data("theo_sd", package = "nlmixr2data")

Using the same dataset preserves continuity.

Students have already:

  • inspected the dataset
  • reviewed event records
  • visualized concentration-time profiles
  • learned the structural model behind the profiles

Now the same dataset is used for formal model estimation.

Module Workflow

Conceptually, this module follows:

Reviewed Dataset
↓
nlmixr2 Model Function
↓
Initial Estimates
↓
FOCEi Estimation
↓
Fit Object
↓
Parameter Interpretation
↓
Predictions and Residuals

This is the first full bridge from theory to model fitting.

How This Module Connects to the previous module

The previous module used a manually written structural function:

one_comp_oral(time, dose, ka, CL, V)

This module expresses the same modeling idea using nlmixr2:

model({
  ka <- exp(tka + eta.ka)
  cl <- exp(tcl + eta.cl)
  v  <- exp(tv  + eta.v)

  linCmt() ~ prop(prop.err)
})

The concepts are the same:

  • absorption
  • clearance
  • volume
  • concentration prediction

But now the model is estimated from data and includes population variability.

What This Module Does Not Fully Cover Yet

This module introduces key model output, but it does not yet provide a full diagnostic evaluation.

The next module will focus on:

  • goodness-of-fit plots
  • residual diagnostics
  • visual predictive checks
  • model qualification

For now, the priority is understanding the first estimated model.

Expected Outputs

By the end of this module, you should have:

  • written a basic nlmixr2 model
  • fit the model to theo_sd
  • inspected the fit object
  • interpreted typical parameter values
  • extracted predictions and residuals
  • prepared for formal diagnostics

Next Step

Start with Lesson 1 to write your first nlmixr2 population PK model.