Hyperion is a companion R packge to the cli tool pharos for managing and running pharamceutical models directly from R. NONMEM is the first supported modelling software.
Installation
You can install the development version of hyperion from GitHub with:
# install.packages("pak")
pak::pak("A2-ai/hyperion")Getting started
To initialize hyperion/pharos use the hyperion::init() cfunction to create a pharos.toml configuration file
library(hyperion)
#>
#>
#> ── pharos configuration ────────────────────────────────────────────────────────
#> ✔ pharos.toml found: /data/user-homes/matthews/Packages/hyperion/pharos.toml
#> ── hyperion options ────────────────────────────────────────────────────────────
#> ✔ hyperion.significant_number_display : 4
#> ── hyperion nonmem object options ──────────────────────────────────────────────
#> ✔ hyperion.nonmem_model.show_included_columns : FALSE
#> ✔ hyperion.nonmem_summary.rse_threshold : 50
#> ✔ hyperion.nonmem_summary.shrinkage_threshold : 30
test_data_dir <- system.file("extdata", package = "hyperion")
if (!file.exists("pharos.toml")) {
hyperion::init(".")
}The pharos.toml file contains several configuration options for NONMEM and pharos. You can see more detailed explanations from pharos
Checking a model
You can check a model for correct compilation before submitting to catch any data path issues, or syntax errors within the control stream with:
check_model(file.path(test_data_dir, "models", "onecmt", "run002a.mod"))
#> WARNINGS AND ERRORS (IF ANY) FOR PROBLEM 1
#>
#> (WARNING 2) NM-TRAN INFERS THAT THE DATA ARE POPULATION.
#>
#> Note: Analytical 2nd Derivatives are constructed in FSUBS but are never used.
#> You may insert $ABBR DERIV2=NO after the first $PROB to save FSUBS construction and compilation time
#> [1] 0
check_model(file.path(test_data_dir, "models", "onecmt", "run004.mod"))
#> AN ERROR WAS FOUND IN THE CONTROL STATEMENTS.
#>
#> AN ERROR WAS FOUND ON LINE 11 AT THE APPROXIMATE POSITION NOTED:
#> TVCL = THETA1
#> X
#> THE CHARACTERS IN ERROR ARE: THETA1
#> 208 UNDEFINED VARIABLE.
#> [1] 4Viewing a model object
Hyperion can read .mod files to give an overview of the mod file with:
run002 <- read_model(file.path(test_data_dir, "models", "onecmt", "run002.mod"))
run002NONMEM Model: run002
Problem: Base one-compartment oral absorption model
Run Status: Run
Dataset: ../../data/derived/onecmpt-oral-30ind.csv
Ignore: @
Theta Parameters
| Parameter | Initial | Lower | Fixed | Comment |
|---|---|---|---|---|
| THETA1 | 1.24 | 0 | No | TVCL (L/hr) |
| THETA2 | 40.86 | 0 | No | TVV (L) |
| THETA3 | 1.24 | 0 | No | TVKA (1/hr) |
Omega Parameters
| Parameter | Initial | Fixed | Comment |
|---|---|---|---|
| OMEGA(1,1) | 0.131 | No | OM1 TVCL :EXP |
| OMEGA(2,2) | 0.136 | No | OM2 TVV :EXP |
| OMEGA(3,3) | 0.1 | No | OM3 TVKA :EXP |
Sigma Parameters
| Parameter | Initial | Fixed | Comment |
|---|---|---|---|
| SIGMA(1,1) | 0.0364 | No | SIG1 Proportional error (variance, 20% CV) |
| SIGMA(2,2) | 0.01 | No | SIG2 Additive error (variance, 0.01 mg/L SD) |
Running a model
You can submit a model to a slurm or sge grid using the following commands:
submit_model_to_slurm(run002, ncpu = 1)
submit_model_to_sge(run002, ncpu = 1)Model summary
After running a model you can view run details and final estimates with:
summary(run002)Model Summary: run002
Problem: Base one-compartment oral absorption model
Records: 240 | Observations: 210 | Subjects: 30
Final OFV: -103.5
Estimation Methods
-
First Order Conditional Estimation with Interaction
- Condition Number: 29.63
Heuristic Checks
[OK] Minimization Successful
[OK] Covariance Step Successful
[OK] No Eigenvalue Issues
[OK] No Parameters Near Boundary
[OK] No Hessian Resets
Theta Parameters
| Parameter | Estimate | SE | RSE (%) | Fixed |
|---|---|---|---|---|
| TVCL | 1.247 | 0.1288 | 10.33 | No |
| TVV | 40.85 | 3.027 | 7.411 | No |
| TVKA | 1.244 | 0.1134 | 9.117 | No |
Omega Parameters
| Parameter | Random Effect | Estimate | SE | RSE (%) | Shrinkage (%) | Fixed |
|---|---|---|---|---|---|---|
| OM1 (TVCL) | ETA1 | 0.1304 | 0.06019 | 46.15 | 18.06 | No |
| OM2 (TVV) | ETA2 | 0.1363 | 0.03971 | 29.13 | 4.986 | No |
| OM3 (TVKA) | ETA3 | 0.1144 | 0.06144 | 53.71 | 27.19 | No |
Sigma Parameters
| Parameter | Random Effect | Estimate | SE | RSE (%) | Shrinkage (%) | Fixed |
|---|---|---|---|---|---|---|
| SIGMA(1,1) | EPS1 | 0.03723 | 0.0116 | 31.16 | 15.44 | No |
| SIGMA(2,2) | EPS2 | 0.006607 | 0.02792 | 422.6 | 15.44 | No |
Copying a model
You can copy a model to a new control stream and alter the initial estimates of the new model. This will create a new mod file and a *_metadata.json file that contains the description and which model it is based on.
copy_model(
from = file.path(test_data_dir, "models", "onecmt", "run002.mod"),
to = file.path(test_data_dir, "models", "onecmt", "run002a.mod"),
update = "all", # sets initial estimates of `to` with final estimates of `from`
jitter = 0.1, # jitters run002a initial estimates by 10%
description = "Some description about what makes run002a different",
overwrite = TRUE,
seed = 804831
)
#> NULLModel lineage
If you use hyperion to copy models you can extract the model lineage with
get_model_lineage(file.path(test_data_dir, "models", "onecmt"))Hyperion Model Tree
ℹ️ Models: 9
-
run001 - Base model
- run004 - Updating run001 to run004 with jittered params …
- run005 - Updating run001 to run004 with jittered params …
-
run002 - Adding COV step, unfixing eps(2)
- run002b001 - Jittering initial sigma estimates, using theta/…
-
run003 - Jittering initial estimates
- run003b2 - Updating run003 with mod object
- run003b1 - Updating run003 to 003b1 with jittered params. …
- run002a - Some description about what makes run002a diffe…