This vignette takes the user through some basic scenarios for
defining, formatting, and making parameter tables using
pmparams. For more information how to effectively integrate
pmparams into your workflow, visit the
MeRGE Expo: Parameter Tables .
We begin by creating a parameter key that tells R how to interpret you parameter values. Our code require four arguments for each parameter:
If you have a model that uses theta in the $ERROR block, make sure
that the theta section’s panel is “RV” so that pmparams
functions can properly identify it.
It is recommended to use a parameter key yaml, but
pmparams works for parameter key tibbles.
A more detailed walk-through of generating the parameter key is available here: MeRGE Expo: Creating a Parameter Key .
paramKeyPath <- system.file("model/nonmem/pk-parameter-key-new.yaml", package = "pmparams")
paramKey <- yaml::yaml.load_file(paramKeyPath)
head(unlist(paramKey))
#> THETA1.abb THETA1.desc
#> "KA (1/h)" "First order absorption rate constant"
#> THETA1.panel THETA1.trans
#> "struct" "logTrans"
#> THETA2.abb THETA2.desc
#> "V2/F (L)" "Apparent central volume"pmparams allows for different parameter estimate input
types: * path to model directory * bbr NONMEM model * data.frame of
parameter estimates
For this example, we will use the path to the model directory.
paramEstimatePath <- system.file("model/nonmem/102", package = "pmparams")We will now join parameter estimates and parameter key. Note: this is an inner_join, so only parameters included in the model output and parameter key will be kept in the table. This was done so that, if your base and final model used the same structural THETAs and random parameters, the same parameter key could be used for both. The additional covariate THETAs defined in the parameter key YAML would simply be ignored when creating the base model parameter table.
Additionally, define_param_table performs checks and
calculates confidence intervals.
df1 <- define_param_table(.estimates = paramEstimatePath,
.key = paramKeyPath)
#> [1] "Model path provided: /data/pmparams/renv/library/R-4.1/x86_64-pc-linux-gnu/pmparams/model/nonmem/102"
#> [1] "Parameter table yaml path provided: /data/pmparams/renv/library/R-4.1/x86_64-pc-linux-gnu/pmparams/model/nonmem/pk-parameter-key-new.yaml"
head(df1)
#> # A tibble: 6 × 33
#> parameter_names estimate stderr random_effect_sd random_effect_sdse fixed
#> <chr> <dbl> <dbl> <dbl> <dbl> <lgl>
#> 1 THETA1 0.434 0.0629 NA NA FALSE
#> 2 THETA2 4.12 0.0276 NA NA FALSE
#> 3 THETA3 1.12 0.0328 NA NA FALSE
#> 4 THETA4 4.21 0.0192 NA NA FALSE
#> 5 THETA5 1.29 0.0354 NA NA FALSE
#> 6 OMEGA(1,1) 0.221 0.0530 0.470 0.0564 FALSE
#> # ℹ 27 more variables: diag <lgl>, shrinkage <dbl>, name <chr>, abb <chr>,
#> # desc <chr>, panel <chr>, trans <chr>, nrow <int>, transTHETA <lgl>,
#> # THETAERR <lgl>, TH <lgl>, OM <lgl>, S <lgl>, LOG <lgl>, LOGIT <lgl>,
#> # lognormO <lgl>, Osd <lgl>, logitOsd <lgl>, propErr <lgl>, addErr <lgl>,
#> # addErrLogDV <lgl>, value <dbl>, se <dbl>, corr_SD <chr>, lower <dbl>,
#> # upper <dbl>, ci_level <dbl>Now, we perform some house-keeping based on the new parameter key
information, calculate any summary statistics (the 95% confidence
intervals are calculated by default), and format the values for the
report using format_param_table.
df2 <- format_param_table(df1)Usually define_param_table and
format_param_table are run together in a single call like
this:
df2 <- define_param_table(.estimates = paramEstimatePath,
.key = paramKeyPath) %>%
format_param_table()
#> [1] "Model path provided: /data/pmparams/renv/library/R-4.1/x86_64-pc-linux-gnu/pmparams/model/nonmem/102"
#> [1] "Parameter table yaml path provided: /data/pmparams/renv/library/R-4.1/x86_64-pc-linux-gnu/pmparams/model/nonmem/pk-parameter-key-new.yaml"
head(df2)
#> type abb greek
#> 1 Structural model parameters KA (1/h) $\\exp(\\theta_{1})$
#> 2 Structural model parameters V2/F (L) $\\exp(\\theta_{2})$
#> 3 Structural model parameters CL/F (L/h) $\\exp(\\theta_{3})$
#> 4 Structural model parameters V3/F (L) $\\exp(\\theta_{4})$
#> 5 Structural model parameters Q/F (L/h) $\\exp(\\theta_{5})$
#> 6 Interindividual variance parameters IIV-KA $\\Omega_{(1,1)}$
#> desc value ci_95
#> 1 First order absorption rate constant 1.54 1.36, 1.75
#> 2 Apparent central volume 61.5 58.2, 64.9
#> 3 Apparent clearance 3.05 2.86, 3.25
#> 4 Apparent peripheral volume 67.4 64.9, 69.9
#> 5 Apparent intercompartmental clearance 3.62 3.38, 3.88
#> 6 Variance of absorption 0.221 [CV\\%=49.7] 0.117, 0.324
#> shrinkage
#> 1 -
#> 2 -
#> 3 -
#> 4 -
#> 5 -
#> 6 17.9We leverage make_pmtable to generate fixed effects and
random effects parameter tables
tableList <- list()
#grab footnotes
footnote <- param_notes(.ci = 95)
##fixed
tableList$fixed <- make_pmtable(df2, .pmtype = "fixed") %>%
#abbreviations
st_notes(footnote$ci, footnote$se) %>%
st_notes_str() %>%
#equations
st_notes(footnote$ciEq)
tableList$fixed %>%
stable() %>%
st_asis()
##random
tableList$random <- make_pmtable(df2, .pmtype = "random") %>%
#abbreviations
st_notes(footnote$ci, footnote$se) %>%
st_notes_str() %>%
#equations
st_notes(footnote$cvOmegaEq, footnote$cvSigmaEq)
tableList$random %>%
stable() %>%
st_asis()If you want to add or overwrite pre-defined pmtables
argument, simply pipe onto the make_pmtable tibble:
pmparams exports two functions for appending bootstrap
estimates to parameter tables. See the
Reference Log for more details.