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
to install the latest release
install.packages("hyperion", repos = c("hyperion" = "https://prism.dev.a2-ai.cloud/rpkgs/hyperion-eco/v2", getOption("repos")))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 CLI version mismatch: installed 0.5.1, expected 0.6.0 (/Users/mattsmith/.cargo/bin/pharos)
#> ✔ pharos.toml found: /private/var/folders/bx/l0m1kftd7m93lvrc4m3_309c0000gn/T/Rtmpb0QPCL/hyperion-readme-412d33c561c0/pharos.toml
#> └ hyperion.config_dir : (unset)
#> ── 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
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("extdata", "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("extdata", "models", "onecmt", "run004.mod"))Viewing a model object
Hyperion can read .mod files to give an overview of the mod file with:
run002 <- read_model(file.path("extdata", "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] No Objective Function Failure
[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("extdata", "models", "onecmt", "run002.mod"),
to = file.path("extdata", "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
Hyperion Model Tree
ℹ️ Models: 9
-
extdata/models/onecmt/run001 base | Base model
-
extdata/models/onecmt/run002 Adding COV step, unfixing eps(2)
- extdata/models/onecmt/run002b001 not run, 2cmt | Jittering initial sigma estimates, using theta/…
-
extdata/models/onecmt/run003 key | Jittering initial estimates
- extdata/models/onecmt/run003b1 Updating run003 to 003b1 with jittered params. …
- extdata/models/onecmt/run003b2 Updating run003 with mod object
- extdata/models/onecmt/run004 Updating run001 to run004 with jittered params …
- extdata/models/onecmt/run005 Updating run001 to run004 with jittered params …
-
extdata/models/onecmt/run002 Adding COV step, unfixing eps(2)
- extdata/models/onecmt/run002a Some description about what makes run002a diffe…