Getting Started with lstparsR
Raban Heller
Dominik Selzer
Simeon Rüdesheim
Christiane Dings
Thorsten Lehr
Source:vignettes/getting-started.Rmd
getting-started.RmdOverview
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 returnsNULLfor 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 : TRUEThe 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.7Each 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.7Extracting 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.9Shrinkage 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.9Extracting 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.3Objective Function Value
fetch_ofv(lst)
#> [1] 1873.406For 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.17029All 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.17029Runs 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] NASynthetic 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 completedParsing 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 NABatch 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.