Skip to contents

Overview

lstparsR reads NONMEM .lst listing files and extracts parameter estimates into tidy tibbles. It is designed for population pharmacokinetic and pharmacodynamic (PK/PD) workflows where many model runs need to be parsed programmatically.

Key design choices:

  • Parameter output is returned as tibbles with consistent column names.
  • Missing optional quantities (e.g., standard errors when the covariance step is absent) are NA. Missing required parameter sections raise errors; fetch_all() catches these, warns, and returns NULL for failed elements.
  • Both VECTOR blocks (THETA) and lower-triangular MATRIX blocks (OMEGA, SIGMA) are handled, including multi-line parameter sets.

Reading a Listing File

Use read_lst_file() to load a .lst file into an S3 object of class "lst". The examples use synthetic listings that ship with the package (see Synthetic Example Listings); this one is a FOCE-I run with a complete covariance step:

path <- system.file("extdata", "lst", "s01_focei_cov_success.lst",
                    package = "lstparsR")
lst  <- read_lst_file(path)
lst
#> <lst> NONMEM listing file: 456 lines
summary(lst)
#> <lst> NONMEM listing file
#>   Lines            : 456
#>   Estimation method: FIRST ORDER CONDITIONAL ESTIMATION WITH INTERACTION
#>   Covariance step  : TRUE

The lst object is simply a character vector (one element per line) with class "lst" attached. All fetch_* functions require this class.

Extracting THETA (Fixed Effects)

fetch_thetas(lst)
#> # A tibble: 4 × 4
#>   parameter estimate    se   rse
#>   <chr>        <dbl> <dbl> <dbl>
#> 1 TH_1         4.37  0.312  7.14
#> 2 TH_2        31.2   2.05   6.57
#> 3 TH_3         1.15  0.143 12.4 
#> 4 TH_4         0.682 0.121 17.7

Each row corresponds to one THETA parameter. The se and rse columns contain the standard error and relative standard error (as a percentage), respectively.

Use the digits argument to round RSE values:

fetch_thetas(lst, digits = 1)
#> # A tibble: 4 × 4
#>   parameter estimate    se   rse
#>   <chr>        <dbl> <dbl> <dbl>
#> 1 TH_1         4.37  0.312   7.1
#> 2 TH_2        31.2   2.05    6.6
#> 3 TH_3         1.15  0.143  12.4
#> 4 TH_4         0.682 0.121  17.7

Extracting OMEGA (Random Effects)

fetch_etas() extracts the diagonal of the OMEGA covariance matrix, plus ETA shrinkage when reported:

fetch_etas(lst)
#> # A tibble: 3 × 5
#>   parameter estimate     se   rse shrinkage
#>   <chr>        <dbl>  <dbl> <dbl>     <dbl>
#> 1 ETA1        0.0841 0.0213  25.3      8.42
#> 2 ETA2        0.0529 0.0187  35.3     21.3 
#> 3 ETA3        0.312  0.0954  30.6     37.9

Shrinkage values can be rounded separately:

fetch_etas(lst, digits = 1, shk_digits = 1)
#> # A tibble: 3 × 5
#>   parameter estimate     se   rse shrinkage
#>   <chr>        <dbl>  <dbl> <dbl>     <dbl>
#> 1 ETA1        0.0841 0.0213  25.3       8.4
#> 2 ETA2        0.0529 0.0187  35.3      21.3
#> 3 ETA3        0.312  0.0954  30.6      37.9

Extracting SIGMA (Residual Error)

fetch_sigmas(lst)
#> # A tibble: 1 × 4
#>   parameter estimate      se   rse
#>   <chr>        <dbl>   <dbl> <dbl>
#> 1 EPS1        0.0277 0.00341  12.3

Objective Function Value

fetch_ofv(lst)
#> [1] 1873.406

For failed runs, fetch_ofv() falls back to the workflow footer (OFV = ...) if the standard #OBJV: line is absent.

Condition Number

The condition number is computed as the ratio of the largest to smallest eigenvalue of the correlation matrix of parameter estimates. Values above 1000 suggest numerical instability:

fetch_condn(lst)
#> [1] 3.17029

All at Once

fetch_all() runs every parser in a single call. Individual parser failures are caught and returned as NULL with a warning, so a single problematic section does not abort the entire extraction:

result <- fetch_all(lst)
names(result)
#> [1] "thetas" "etas"   "sigmas" "ofv"    "condn"
result$thetas
#> # A tibble: 4 × 4
#>   parameter estimate    se   rse
#>   <chr>        <dbl> <dbl> <dbl>
#> 1 TH_1         4.37  0.312  7.14
#> 2 TH_2        31.2   2.05   6.57
#> 3 TH_3         1.15  0.143 12.4 
#> 4 TH_4         0.682 0.121 17.7
result$ofv
#> [1] 1873.406
result$condn
#> [1] 3.17029

Runs Without a Covariance Step

When NONMEM did not run or complete a covariance step, SE, RSE, and condition number are returned as NA:

path2 <- system.file("extdata", "lst", "s39_focei_no_cov.lst",
                     package = "lstparsR")
lst2  <- read_lst_file(path2)
fetch_thetas(lst2)
#> # A tibble: 4 × 4
#>   parameter estimate    se   rse
#>   <chr>        <dbl> <dbl> <dbl>
#> 1 TH_1         4.46     NA    NA
#> 2 TH_2        30.7      NA    NA
#> 3 TH_3         1.18     NA    NA
#> 4 TH_4         0.701    NA    NA
fetch_condn(lst2)
#> [1] NA

Synthetic Example Listings

The package ships 39 small, invented listings in extdata/lst, generated by a script (data-raw/make_synthetic_lst.R in the source repository). Each case exercises one estimation method, run outcome or layout feature, from a successful FOCE-I run with a complete covariance step to aborted covariance steps, chained $ESTIMATION records, wrapped parameter records and truncated files. manifest.csv describes the cases and the values they contain:

corpus   <- system.file("extdata", "lst", package = "lstparsR")
manifest <- read.csv(file.path(corpus, "manifest.csv"))
head(manifest[, c("case_id", "final_method", "covariance")])
#>   case_id                                        final_method    covariance
#> 1     s01 First Order Conditional Estimation with Interaction     completed
#> 2     s02                  First Order Conditional Estimation     completed
#> 3     s03                                         First Order     completed
#> 4     s04   Laplacian Conditional Estimation with Interaction     completed
#> 5     s05                                 Iterative Two Stage not requested
#> 6     s06   Stochastic Approximation Expectation-Maximization     completed

Parsing a few of them side by side shows how unavailable quantities are reported: standard errors and the condition number become NA when the covariance step was aborted or not reached, and fetch_all() returns NULL for parameter tables that a truncated listing does not contain.

cases <- c("s01", "s09", "s15", "s18", "s32")
files <- file.path(corpus, manifest$file[match(cases, manifest$case_id)])
runs  <- lapply(files, function(f) suppressWarnings(fetch_all(read_lst_file(f))))
data.frame(
  case       = cases,
  covariance = manifest$covariance[match(cases, manifest$case_id)],
  thetas     = vapply(runs, function(r) NROW(r$thetas), integer(1)),
  se_th1     = vapply(runs, function(r) if (is.null(r$thetas)) NA else r$thetas$se[1], numeric(1)),
  ofv        = vapply(runs, function(r) r$ofv, numeric(1)),
  condn      = round(vapply(runs, function(r) r$condn, numeric(1)), 2)
)
#>   case                 covariance thetas se_th1       ofv condn
#> 1  s01                  completed      4  0.312  1873.406  3.17
#> 2  s09      from posterior sample      2  0.238 -2187.645  6.81
#> 3  s15                    aborted      4     NA  1885.071    NA
#> 4  s18 completed (no eigenvalues)      4  0.329  1871.952    NA
#> 5  s32                interrupted      0     NA  1874.109    NA

Batch Processing

A common pattern is to parse many .lst files at once:

library(purrr)

lst_files <- list.files("models/", pattern = "\\.lst$", full.names = TRUE)

results <- map(lst_files, \(f) {
  lst <- read_lst_file(f)
  fetch_all(lst)
})

# Combine all THETA tables
all_thetas <- map_dfr(results, "thetas", .id = "run")

Estimation Headers and Output Layouts

lstparsR recognizes the following NONMEM estimation method headers:

  • First Order (FO)
  • First Order Conditional Estimation (FOCE)
  • First Order Conditional Estimation with Interaction (FOCE-I)
  • Laplacian Conditional Estimation, with or without interaction (LAPLACE)
  • Iterative Two Stage (ITS)
  • Stochastic Approximation Expectation-Maximization (SAEM)
  • Importance Sampling (IMP), including evaluation-only steps
  • Importance Sampling Assisted by Mode A Posteriori (IMPMAP)
  • MCMC Bayesian Analysis (BAYES)

Numerical regression tests cover FOCE-I listings, controlled edge cases and a synthetic corpus of invented listings for every method above (see extdata/lst/manifest.csv); FO listings have additional execution coverage. The synthetic layouts of the EM and Bayesian methods follow the NONMEM 7 documentation. Recognizing a method header does not validate every layout or posterior summary from that method. The parsers expect the fixed-format result sections shown in the examples. Compare results with the original listing for unfamiliar layouts. Parsing does not validate the scientific model or its estimates.

Interactive Exploration

For interactive use, launch the built-in Shiny application:

lstparsR::run_app()

This opens a browser-based interface where you can upload .lst files, view parsed results in tables, and download them as CSV or RDS.