hyperion

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] 4

Viewing 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"))
run002

NONMEM 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
)
#> NULL

Model 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…