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

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("vignettes/test_data/models/onecmt/run002a.mod") |> 
  cat()
#>   
#>  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
#> 

check_model("vignettes/test_data/models/onecmt/run004.mod") |> 
  cat()
#>  
#>  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.
#> 
#> nmtran failed with exit code 4

Viewing a model object

Hyperion can read .mod files to give an overview of the mod file with:

read_model("vignettes/test_data/models/onecmt/run002.mod")

NONMEM Model: run002

Problem: Base one-compartment oral absorption model

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.100	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.0100	No	SIG2 Additive error (variance, 0.01 mg/L SD)

Running a model

There is no current support from hyperion to run a model, but SLURM job submission will be coming soon.

Model summary

After running a model you can view run details and final estimates with:

get_model_summary("vignettes/test_data/models/onecmt/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 (%)
TVCL	1.247	0.1288	10.330
TVV	40.850	3.0270	7.411
TVKA	1.244	0.1134	9.117

Omega Parameters

Parameter	Random Effect	Estimate	SE	RSE (%)	Shrinkage (%)
OM1 (TVCL)	ETA1	0.1304	0.06019	46.15	18.060
OM2 (TVV)	ETA2	0.1363	0.03971	29.13	4.986
OM3 (TVKA)	ETA3	0.1144	0.06144	53.71	27.190

Sigma Parameters

Parameter	Random Effect	Estimate	SE	RSE (%)	Shrinkage (%)
SIGMA(1,1)	EPS1	0.037230	0.01160	31.16	15.44
SIGMA(2,2)	EPS2	0.006607	0.02792	422.6	15.44

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 = "vignettes/test_data/models/onecmt/run002.mod", 
  to = "vignettes/test_data/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 = 804
)
#> NULL

Model lineage

If you use hyperion to copy models you can extract the model lineage with

get_model_lineage("vignettes/test_data/models/onecmt")

Hyperion Model Tree

ℹ️ Models: 7

• run001
  • run004 - Updating run001 to run004 with jittered params …
  • run002 - Adding COV step, unfixing eps(2)
    • run003 - Jittering initial estimates
      • run003b1 - Updating run003 to 003b1 with jittered params
    • run002a - Some description about what makes run002a diffe…
    • run002b001 - Jittering initial sigma estimates, using theta/…