Skip to contents

Hyperion Model

Source: vignettes/hyperion_model.Rmd
hyperion_model.Rmd
library(hyperion)
#> 
#> 
#> ── pharos configuration ────────────────────────────────────────────────────────
#> ✔ pharos.toml found: /data/user-homes/tariq/projects/prism-pkgdocs-build/installed-pkgs/2026-03-02/hyperion_0.3.2/vignettes/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")

Hyperion Model object 

mod <- read_model(file.path(test_data_dir, "mod", "1001.mod"))
mod

NONMEM Model: 1001

Problem: PK Structural Model

Run Status: Not Run

Dataset: ../../../../data/derived/PK_Oral_Ex1.csv

Ignore: @

Theta Parameters

Parameter Initial Lower Fixed Comment
THETA1 19 0 No CL/F (L/h)
THETA2 304 0 No VC/F (L)
THETA3 2 0 No KA (1/hr)
THETA4 1 NA Yes F1 (fraction)

Omega Parameters

Parameter Initial Fixed Comment
OMEGA(1,1) 0.1 No OM1 CL :EXP
OMEGA(2,2) 0.1 No OM2 VC :EXP
OMEGA(3,3) 0.1 No OM3 KA :EXP

Sigma Parameters

Parameter Initial Fixed Comment
SIGMA(1,1) 0.1 No SIG1
SIGMA(2,2) 2 No SIG2 

mod <- read_model(file.path(test_data_dir, "models", "onecmt", "run002b001.mod"))
mod

NONMEM Model: run002b001

Problem: Base one-compartment oral absorption model created from pharos see run002b001_metadata.json for details.

Run Status: Not Run

Dataset: ../../data/derived/onecmpt-oral-30ind.csv

Ignore: @

Theta Parameters

Parameter Initial Lower Fixed Comment
THETA1 1.247 0 No TVCL (L/hr)
THETA2 40.85 0 No TVV (L)
THETA3 1.244 0 No TVKA (1/hr)

Omega Parameters

Parameter Initial Fixed Comment
OMEGA(1,1) 0.1304 No OM1 TVCL :EXP
OMEGA(2,2) 0.1363 No OM2 TVV :EXP
OMEGA(3,3) 0.114 No OM3 TVKA :EXP

Sigma Parameters

Parameter Initial Fixed Comment
SIGMA(1,1) 0.04812 No SIG1 Proportional error (variance, 20% CV)
SIGMA(2,2) 0.0059 No SIG2 Additive error (variance, 0.01 mg/L SD) 

mod_nm <- read_model(file.path(test_data_dir, "mod", "nmexample.mod"))
mod_nm

NONMEM Model: nmexample

Problem: RUN# Example 1 (from samp5l)

Run Status: Not Run

Dataset: example1.csv

Ignore: C

Aliased Columns: CONC → DV, DOSE → AMT

Theta Parameters

Parameter Initial Lower Fixed Comment
THETA1 2 0.001 No [LN(CL)]
THETA2 2 0.001 No [LN(V1)]
THETA3 2 0.001 No [LN(Q)]
THETA4 2 0.001 No [LN(V2)]

Omega Parameters

Parameter Initial Fixed Comment
OMEGA(1,1) 0.15 No [P]
OMEGA(2,1) 0.01 No [F]
OMEGA(2,2) 0.15 No [P]
OMEGA(3,1) 0.01 No [F]
OMEGA(3,2) 0.01 No [F]
OMEGA(3,3) 0.15 No [P]
OMEGA(4,1) 0.01 No [F]
OMEGA(4,2) 0.01 No [F]
OMEGA(4,3) 0.01 No [F]
OMEGA(4,4) 0.15 No [P]

Sigma Parameters

Parameter Initial Fixed Comment
SIGMA(1,1) 0.6 No [P] 

mod_e <- read_model(file.path(test_data_dir, "mod", "everything.mod"))
mod_e

NONMEM Model: everything

Problem: Some header #2

Run Status: Not Run

Dataset: ...csv

Ignore: #, DVID.EQ.3, ID.EQ.3.14

Records: 200

Dropped Columns: DATE

Aliased Columns: AMT → DOSE

Theta Parameters

Parameter Initial Lower Upper Fixed Comment
THETA1 1.5 NA NA No THETA(1) and THETA(2)
THETA2 0.5 0 2 No THETA(1) and THETA(2)
THETA3 2.3 NA NA Yes THETA(3)
THETA4 0.8 NA NA No THETA(4) and THETA(5)
THETA5 0.25 NA NA No THETA(4) and THETA(5)
THETA6 2.3 1 NA Yes THETA(6)
THETA7 0.75 NA NA Yes THETA(7)

Omega Parameters

Parameter Initial Lower Upper Fixed Parametrization Comment
OMEGA(1,1) 0.04 NA NA No ETA(1) - CL (diagonal)
OMEGA(2,2) 0.17 NA NA No
OMEGA(3,3) 0.2 NA NA No Correlation ETA(2) - V (SD)
OMEGA(4,3) 0.3 NA NA No Correlation ETA(2)-ETA(3) correlation, ETA(3) - KA (SD)
OMEGA(4,4) 0.15 NA NA No Correlation ETA(2)-ETA(3) correlation, ETA(3) - KA (SD)
OMEGA(5,5) 0.2 NA NA No Correlation ETA(2) - V (SD)
OMEGA(6,5) 0.3 NA NA No Correlation ETA(2)-ETA(3) correlation, ETA(3) - KA (SD)
OMEGA(6,6) 0.15 NA NA No Correlation ETA(2)-ETA(3) correlation, ETA(3) - KA (SD)
OMEGA(7,7) 0.1 0 1 Yes ETA(6) - fixed diagonal

Sigma Parameters

Parameter Initial Fixed Comment
SIGMA(1,1) 0.01 No Proportional error variance
SIGMA(2,1) 0.002 No Prop-Add covariance, Additive error variance
SIGMA(2,2) 0.25 No Prop-Add covariance, Additive error variance 
names(mod)
#>  [1] "problem"          "input_columns"    "data"             "subroutines"     
#>  [5] "theta_parameters" "omega_blocks"     "sigma_blocks"     "estimations"     
#>  [9] "tables"           "simulation"

attributes(mod) |> names()
#> [1] "names"        "filename"     "model_source" "run_status"   "class"
read_model(file.path(test_data_dir, "models", "onecmt", "run001.mod")) |>
  check_dataset()

Dataset Check

Path ../../../../../../.cache/rv/696fcbda91/4.5/x86_64/noble/9b8ad1be11/hyperion/extdata/data/derived/onecmpt-oral-30ind.csv
Hash 8d8189cfc45dc4d56c295ca990a131e086f53d874aa91e730c1e8856e840b005 

read_model(file.path(test_data_dir, "models", "onecmt", "run002.mod")) |>
  check_dataset()

Dataset Check

Path ../../../../../../.cache/rv/696fcbda91/4.5/x86_64/noble/9b8ad1be11/hyperion/extdata/data/derived/onecmpt-oral-30ind.csv
Hash 8d8189cfc45dc4d56c295ca990a131e086f53d874aa91e730c1e8856e840b005 

read_model(file.path(test_data_dir, "models", "onecmt", "run003.mod")) |>
  check_dataset()

Dataset Check

Path ../../../../../../.cache/rv/696fcbda91/4.5/x86_64/noble/9b8ad1be11/hyperion/extdata/data/derived/onecmpt-oral-30ind.csv
Hash 8d8189cfc45dc4d56c295ca990a131e086f53d874aa91e730c1e8856e840b005 
check_model(file.path(test_data_dir, "models", "onecmt", "run001.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
summary(file.path(test_data_dir, "models", "onecmt", "run003"))
#>    Length     Class      Mode 
#>         1 character character

model summary can be generated from model object 

mod <- read_model(file.path(test_data_dir, "models", "onecmt", "run003.mod"))
mod |>
    summary()

Model Summary: run003

Problem: Base one-compartment oral absorption model created from pharos see run003_metadata.json for details.

Records: 240 | Observations: 210 | Subjects: 30

Final OFV: -109.8

Estimation Methods

  • First Order Conditional Estimation with Interaction
    • Condition Number: 6.172

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.325 0.1115 8.411 No
TVV 40.16 2.839 7.069 No
TVKA 1.212 0.1097 9.057 No

Omega Parameters

Parameter Random Effect Estimate SE RSE (%) Shrinkage (%) Fixed
OM1 (TVCL) ETA1 0.1223 0.05036 41.16 13.14 No
OMEGA(2,1) ETA1:ETA2 0.07454 0.03134 42.04 NA No
OM2 (TVV) ETA2 0.1239 0.03675 29.66 4.631 No
OM3 (TVKA) ETA3 0.1224 0.05628 45.97 24.34 No

Sigma Parameters

Parameter Random Effect Estimate SE RSE (%) Shrinkage (%) Fixed
SIGMA(1,1) EPS1 0.03754 0.006035 16.08 14.42 No
SIGMA(2,2) EPS2 0.005272 0.009211 174.7 14.42 No

parameters can be retrieved with model 

mod |> get_parameters()
#>    kind       name random_effect    estimate        sd     corr     stderr
#> 1 THETA       TVCL          <NA>  1.32542000        NA       NA 0.11148400
#> 2 THETA        TVV          <NA> 40.16250000        NA       NA 2.83899000
#> 3 THETA       TVKA          <NA>  1.21172000        NA       NA 0.10974700
#> 4 OMEGA OM1 (TVCL)          ETA1  0.12234200 0.3497740       NA 0.05035540
#> 5 OMEGA OMEGA(2,1)     ETA1:ETA2  0.07454330        NA 0.605513 0.03133500
#> 6 OMEGA  OM2 (TVV)          ETA2  0.12387800 0.3519630       NA 0.03674650
#> 7 OMEGA OM3 (TVKA)          ETA3  0.12241200 0.3498740       NA 0.05627810
#> 8 SIGMA SIGMA(1,1)          EPS1  0.03753710 0.1937450       NA 0.00603493
#> 9 SIGMA SIGMA(2,2)          EPS2  0.00527228 0.0726105       NA 0.00921096
#>          rse shrinkage fixed diagonal
#> 1   8.411221        NA FALSE       NA
#> 2   7.068758        NA FALSE       NA
#> 3   9.057125        NA FALSE       NA
#> 4  41.159536  13.14400 FALSE     TRUE
#> 5  42.035971        NA FALSE    FALSE
#> 6  29.663459   4.63131 FALSE     TRUE
#> 7  45.974333  24.33760 FALSE     TRUE
#> 8  16.077241  14.42190 FALSE     TRUE
#> 9 174.705441  14.42190 FALSE     TRUE

parameter info can be retrieved with model 

info <- get_model_parameter_info(mod)
info

Model Parameter Info

Theta Parameters

parameter name display description unit parameterization
THETA1 TVCL NA NA L/hr NA
THETA2 TVV NA NA L NA
THETA3 TVKA NA NA 1/hr NA

Omega Parameters

parameter name display description parameterization associated_theta
OMEGA(1,1) OM1 NA NA LogNormal TVCL
OMEGA(2,1) OM1,2 NA NA LogNormal TVCL, TVV
OMEGA(2,2) OM2 NA NA LogNormal TVV
OMEGA(3,3) OM3 NA NA LogNormal TVKA

Sigma Parameters

parameter name display description unit parameterization
SIGMA(1,1) SIG1 NA NA NA NA
SIGMA(2,2) SIG2 NA NA NA NA

Parameter Info Audit

Theta Sources

parameter name display description unit parameterization
THETA1 ../../../../../../.cache/rv/696fcbda91/4.5/x86_64/noble/9b8ad1be11/hyperion/extdata/models/onecmt/run003/run003.lst default default ../../../../../../.cache/rv/696fcbda91/4.5/x86_64/noble/9b8ad1be11/hyperion/extdata/models/onecmt/run003/run003.lst default
THETA2 ../../../../../../.cache/rv/696fcbda91/4.5/x86_64/noble/9b8ad1be11/hyperion/extdata/models/onecmt/run003/run003.lst default default ../../../../../../.cache/rv/696fcbda91/4.5/x86_64/noble/9b8ad1be11/hyperion/extdata/models/onecmt/run003/run003.lst default
THETA3 ../../../../../../.cache/rv/696fcbda91/4.5/x86_64/noble/9b8ad1be11/hyperion/extdata/models/onecmt/run003/run003.lst default default ../../../../../../.cache/rv/696fcbda91/4.5/x86_64/noble/9b8ad1be11/hyperion/extdata/models/onecmt/run003/run003.lst default

Omega Sources

parameter name display description parameterization associated_theta
OMEGA(1,1) ../../../../../../.cache/rv/696fcbda91/4.5/x86_64/noble/9b8ad1be11/hyperion/extdata/models/onecmt/run003/run003.lst default default ../../../../../../.cache/rv/696fcbda91/4.5/x86_64/noble/9b8ad1be11/hyperion/extdata/models/onecmt/run003/run003.lst ../../../../../../.cache/rv/696fcbda91/4.5/x86_64/noble/9b8ad1be11/hyperion/extdata/models/onecmt/run003/run003.lst
OMEGA(2,1) ../../../../../../.cache/rv/696fcbda91/4.5/x86_64/noble/9b8ad1be11/hyperion/extdata/models/onecmt/run003/run003.lst default default ../../../../../../.cache/rv/696fcbda91/4.5/x86_64/noble/9b8ad1be11/hyperion/extdata/models/onecmt/run003/run003.lst ../../../../../../.cache/rv/696fcbda91/4.5/x86_64/noble/9b8ad1be11/hyperion/extdata/models/onecmt/run003/run003.lst
OMEGA(2,2) ../../../../../../.cache/rv/696fcbda91/4.5/x86_64/noble/9b8ad1be11/hyperion/extdata/models/onecmt/run003/run003.lst default default ../../../../../../.cache/rv/696fcbda91/4.5/x86_64/noble/9b8ad1be11/hyperion/extdata/models/onecmt/run003/run003.lst ../../../../../../.cache/rv/696fcbda91/4.5/x86_64/noble/9b8ad1be11/hyperion/extdata/models/onecmt/run003/run003.lst
OMEGA(3,3) ../../../../../../.cache/rv/696fcbda91/4.5/x86_64/noble/9b8ad1be11/hyperion/extdata/models/onecmt/run003/run003.lst default default ../../../../../../.cache/rv/696fcbda91/4.5/x86_64/noble/9b8ad1be11/hyperion/extdata/models/onecmt/run003/run003.lst ../../../../../../.cache/rv/696fcbda91/4.5/x86_64/noble/9b8ad1be11/hyperion/extdata/models/onecmt/run003/run003.lst

Sigma Sources

parameter name display description unit parameterization
SIGMA(1,1) ../../../../../../.cache/rv/696fcbda91/4.5/x86_64/noble/9b8ad1be11/hyperion/extdata/models/onecmt/run003/run003.lst default default default default
SIGMA(2,2) ../../../../../../.cache/rv/696fcbda91/4.5/x86_64/noble/9b8ad1be11/hyperion/extdata/models/onecmt/run003/run003.lst default default default default

Copy model 

copy_model(
  from = file.path(test_data_dir, "models", "onecmt", "run003.mod"),
  to = file.path(test_data_dir, "models", "onecmt", "run003b2.mod"), #copies run003 to run003b1 with jittered parameters
  description = "Updating run003 to 003b1 with jittered params",
  jitter = 0.1,
  overwrite = TRUE,
  seed = 804
)
#> NULL
copy_model(
  from = file.path(test_data_dir, "models", "onecmt", "run002.mod"),
  to = file.path(test_data_dir, "models", "onecmt", "run002b001.mod"),
  update = c("theta", "omega"),
  jitter = c(sigma = 0.3), #jitters run002 sigma initial estimates
  description = "Jittering initial sigma estimates, using theta/omega final estimates. Adding covariate",
  overwrite = TRUE,
  seed = 804
)
#> NULL

Copy model accepts hyperion model object 

mod <- read_model(file.path(test_data_dir, "models", "onecmt", "run003.mod"))

mod |> 
    copy_model(
        to = file.path(test_data_dir, "models", "onecmt", "run003b2.mod"),
        update = "all",
        description = "Updating run003 with mod object",
        overwrite = TRUE,
        seed = 804831
    )
#> NULL

Model Lineage 

example_tree <- get_model_lineage(file.path(test_data_dir, "models", "onecmt"))

example_tree

Hyperion Model Tree

ℹ️ Models: 9

  • run001 - Base model
    • 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. …
        • run003b2 - Updating run003 with mod object
      • run002a - Some description about what makes run002a diffe…
      • run002b001 - Jittering initial sigma estimates, using theta/…
    • run005 - Updating run001 to run004 with jittered params …