Skip to contents

Hyperion Model

Source: vignettes/hyperion_model.Rmd
hyperion_model.Rmd
library(hyperion)
#> 
#> 
#> ── pharos configuration ────────────────────────────────────────────────────────
#> ✖ pharos CLI not found on PATH
#> ✔ pharos.toml found: /tmp/RtmpFjMiMC/hyperion-vignette-ad457bf3dfc/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

Hyperion Model object 

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

NONMEM Model: 1001

Problem: PK Structural Model

Run Status: Not Run

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

Ignore: @

Aliased Columns: ATFD → TIME, ODV → DV

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/F :EXP
OMEGA(2,2) 0.1 No OM2 VC/F :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("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("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: DV → CONC, AMT → DOSE

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("mod", "everything.mod"))
mod_e

NONMEM Model: everything

Problem: Some header #2

Run Status: Not Run

Dataset: ..with spaces.csv

Ignore: #, DVID.EQ.3, ID.EQ.3.14, DVID.EQ.3, AGE.GE.18, AGE.GT.3, AGE.LT.100, AGE.LE.65, TYPE.NE.0, TYPE.EQ.1, TYPE.EQN.1, TYPE.NEN.2, TYPE.EQ.1

Records: 200

Dropped Columns: DATE

Aliased Columns: DOSE → AMT

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 0.5 -Inf 10 No THETA with -INF lower bound
THETA4 5 0 Inf No THETA with INF upper bound
THETA5 0.1 0 NA No Three identical THETAs
THETA6 0.1 0 NA No Three identical THETAs
THETA7 0.1 0 NA No Three identical THETAs
THETA8 1.5 0 10 No Named THETA
THETA9 0.5 0 NA No NAMES syntax
THETA10 10 0 NA No NAMES syntax
THETA11 2 0 NA No NAMES syntax
THETA12 1.1 1 NA No Three identical THETAs with NAMES
THETA13 1.1 1 NA No Three identical THETAs with NAMES
THETA14 1.1 1 NA No Three identical THETAs with NAMES
THETA15 2.3 NA NA Yes THETA(3)
THETA16 0.8 NA NA No THETA(4) and THETA(5)
THETA17 0.25 NA NA No THETA(4) and THETA(5)
THETA18 2.3 1 NA Yes THETA(6)
THETA19 0.75 NA NA Yes THETA(7)

Omega Parameters

Parameter Initial Fixed Parametrization Comment
OMEGA(1,1) 0.04 No ETA(1) - CL (diagonal)
OMEGA(2,2) 0.17 No
OMEGA(3,3) 0.2 No Correlation ETA(2) - V (SD)
OMEGA(4,3) 0.3 No Correlation ETA(2)-ETA(3) correlation, ETA(3) - KA (SD)
OMEGA(4,4) 0.15 No Correlation ETA(2)-ETA(3) correlation, ETA(3) - KA (SD)
OMEGA(5,5) 0.2 No Correlation ETA(2) - V (SD)
OMEGA(6,5) 0.3 No Correlation ETA(2)-ETA(3) correlation, ETA(3) - KA (SD)
OMEGA(6,6) 0.15 No Correlation ETA(2)-ETA(3) correlation, ETA(3) - KA (SD)
OMEGA(7,7) 0.01121 Yes
OMEGA(8,7) 0 Yes
OMEGA(8,8) 0.3387 Yes
OMEGA(9,9) 0.1 No
OMEGA(10,9) 0.01 No
OMEGA(10,10) 0.1 No
OMEGA(11,9) 0.01 No
OMEGA(11,10) 0.01 No
OMEGA(11,11) 0.1 No
OMEGA(12,9) 0.01 No
OMEGA(12,10) 0.01 No
OMEGA(12,11) 0.01 No
OMEGA(12,12) 0.1 No
OMEGA(13,13) 0.4 No Label=Value syntax for diagonal
OMEGA(14,14) 0.3 No
OMEGA(15,14) 0.01 No Label=Value syntax in block
OMEGA(15,15) 0.35 No Label=Value syntax in block
OMEGA(16,16) 0.03 No
OMEGA(17,16) 0.01 No
OMEGA(17,17) 0.03 No
OMEGA(18,16) 0.01 No
OMEGA(18,17) 0.01 No
OMEGA(18,18) 0.03 No
OMEGA(19,16) 0.01 No
OMEGA(19,17) 0.01 No
OMEGA(19,18) 0.01 No
OMEGA(19,19) 0.03 No
OMEGA(20,20) 0.2 No Correlation
OMEGA(21,20) 0.3 No Correlation
OMEGA(21,21) 0.15 No Correlation
OMEGA(22,20) 0.1 No Correlation
OMEGA(22,21) 0.05 No Correlation
OMEGA(22,22) 0.3 No Correlation
OMEGA(23,23) 0.2 No Correlation
OMEGA(24,23) 0.3 No Correlation
OMEGA(24,24) 0.15 No Correlation
OMEGA(25,23) 0.1 No Correlation
OMEGA(25,24) 0.05 No Correlation
OMEGA(25,25) 0.3 No Correlation
OMEGA(26,26) 6 Yes
OMEGA(27,26) 0.005 Yes
OMEGA(27,27) 0.3 Yes
OMEGA(28,26) 0.001 Yes
OMEGA(28,27) 0.002 Yes
OMEGA(28,28) 0.1 Yes

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
SIGMA(3,3) 1 Yes
SIGMA(4,4) 0.036 No
SIGMA(5,5) 0.04 No Label=Value syntax for SIGMA
SIGMA(6,6) 0.01 No diagonal SIGMA
SIGMA(7,7) 0.02 No diagonal SIGMA 
names(mod)
#>  [1] "cst"           "tokens"        "problem"       "input_columns"
#>  [5] "data"          "thetas"        "omega_blocks"  "sigma_blocks" 
#>  [9] "estimations"   "tables"        "simulation"    "msfi"         
#> [13] "covariance"    "subroutines"   "abbreviated"   "pk"           
#> [17] "error"         "des"           "pred"

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

Dataset Check

Path data/derived/onecmpt-oral-30ind.csv
Hash 8d8189cfc45dc4d56c295ca990a131e086f53d874aa91e730c1e8856e840b005 

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

Dataset Check

Path data/derived/onecmpt-oral-30ind.csv
Hash 8d8189cfc45dc4d56c295ca990a131e086f53d874aa91e730c1e8856e840b005 

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

Dataset Check

Path data/derived/onecmpt-oral-30ind.csv
Hash 8d8189cfc45dc4d56c295ca990a131e086f53d874aa91e730c1e8856e840b005 
read_model(file.path("models", "onecmt", "run001.mod")) |>
  check_model()
#> 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

model summary can be generated from model object 

mod <- read_model(file.path("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] 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.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
OM1,2 (TVCL, TVV) 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
#> 1 THETA              TVCL          <NA>  1.32542000        NA       NA
#> 2 THETA               TVV          <NA> 40.16250000        NA       NA
#> 3 THETA              TVKA          <NA>  1.21172000        NA       NA
#> 4 OMEGA        OM1 (TVCL)          ETA1  0.12234200 0.3497740       NA
#> 5 OMEGA OM1,2 (TVCL, TVV)     ETA1:ETA2  0.07454330        NA 0.605513
#> 6 OMEGA         OM2 (TVV)          ETA2  0.12387800 0.3519630       NA
#> 7 OMEGA        OM3 (TVKA)          ETA3  0.12241200 0.3498740       NA
#> 8 SIGMA        SIGMA(1,1)          EPS1  0.03753710 0.1937450       NA
#> 9 SIGMA        SIGMA(2,2)          EPS2  0.00527228 0.0726105       NA
#>       stderr        rse shrinkage fixed diagonal
#> 1 0.11148400   8.411221        NA FALSE       NA
#> 2 2.83899000   7.068758        NA FALSE       NA
#> 3 0.10974700   9.057125        NA FALSE       NA
#> 4 0.05035540  41.159536  13.14400 FALSE     TRUE
#> 5 0.03133500  42.035971        NA FALSE    FALSE
#> 6 0.03674650  29.663459   4.63131 FALSE     TRUE
#> 7 0.05627810  45.974333  24.33760 FALSE     TRUE
#> 8 0.00603493  16.077241  14.42190 FALSE     TRUE
#> 9 0.00921096 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 raw_name display description parameterization associated_theta
OMEGA(1,1) OM1 (TVCL) OM1 NA NA LogNormal TVCL
OMEGA(2,1) OM1,2 (TVCL, TVV) OM1,2 NA NA LogNormal TVCL, TVV
OMEGA(2,2) OM2 (TVV) OM2 NA NA LogNormal TVV
OMEGA(3,3) OM3 (TVKA) OM3 NA NA LogNormal TVKA

Sigma Parameters

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

Model information source is captured

Parameter Info Audit

Theta Sources

parameter name display description unit parameterization
THETA1 models/onecmt/run003/run003.lst default default models/onecmt/run003/run003.lst default
THETA2 models/onecmt/run003/run003.lst default default models/onecmt/run003/run003.lst default
THETA3 models/onecmt/run003/run003.lst default default models/onecmt/run003/run003.lst default

Omega Sources

parameter name raw_name display description parameterization associated_theta
OMEGA(1,1) models/onecmt/run003/run003.lst models/onecmt/run003/run003.lst default default models/onecmt/run003/run003.lst models/onecmt/run003/run003.lst
OMEGA(2,1) models/onecmt/run003/run003.lst models/onecmt/run003/run003.lst default default models/onecmt/run003/run003.lst models/onecmt/run003/run003.lst
OMEGA(2,2) models/onecmt/run003/run003.lst models/onecmt/run003/run003.lst default default models/onecmt/run003/run003.lst models/onecmt/run003/run003.lst
OMEGA(3,3) models/onecmt/run003/run003.lst models/onecmt/run003/run003.lst default default models/onecmt/run003/run003.lst models/onecmt/run003/run003.lst

Sigma Sources

parameter name display description unit parameterization
SIGMA(1,1) default default default default default
SIGMA(2,2) default default default default default

Copy model 

copy_model(
  from = file.path("models", "onecmt", "run003.mod"),
  to = file.path("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 accepts hyperion model object 

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

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

Managing metadata and lineage

Set and read metadata

set_metadata_file() writes a JSON metadata sidecar next to a model. The description, tags, based_on, and copied_from fields are stored separately so model provenance can be tracked explicitly.

set_metadata_file(
  file.path("models", "onecmt", "run003.mod"),
  description = "Base one-compartment oral absorption model",
  tags = c("base", "key"),
  based_on = c("run002.mod")
)

Model Metadata

Description Base one-compartment oral absorption model
Tags base, key
Based On models/onecmt/run002.mod 

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

Model Metadata

Description Base one-compartment oral absorption model
Tags base, key
Based On models/onecmt/run002.mod

Populate metadata at copy time

copy_model() accepts based_on and tags so the new model’s metadata is populated as part of the copy.

copy_model(
  from = file.path("models", "onecmt", "run003.mod"),
  to = file.path("models", "onecmt", "run003b2.mod"),
  description = "run003 with jittered params, exploring WT on V",
  based_on = c("run003.mod"),
  tags = c("exploratory", "wt-on-v"),
  jitter = 0.1,
  overwrite = TRUE,
  seed = 804
)
#> NULL

Clear metadata fields

clear_metadata_file() selectively clears based_on, copied_from, and/or tags. Fields not selected are preserved.

clear_metadata_file(
  file.path("models", "onecmt", "run003b2.mod"),
  tags = TRUE
)

Model Metadata

Description run003 with jittered params, exploring WT on V
Tags (none)
Based On models/onecmt/run003.mod

Lineage queries

get_model_lineage() returns the project lineage tree. With no arguments it returns every model rooted at the directory containing pharos.toml.

Hyperion Model Tree

ℹ️ Models: 9

  • models/onecmt/run001 base | Base model

  • models/onecmt/run002 Adding COV step, unfixing eps(2)

    • models/onecmt/run003 base, key | Base one-compartment oral absorption model
      • models/onecmt/run003b2 run003 with jittered params, exploring WT on V

  • models/onecmt/run002a Some description about what makes run002a diffe…

  • models/onecmt/run002b001 not run, 2cmt | Jittering initial sigma estimates, using theta/…

  • models/onecmt/run003b1 Updating run003 to 003b1 with jittered params. …

  • models/onecmt/run004 Updating run001 to run004 with jittered params …

  • models/onecmt/run005 Updating run001 to run004 with jittered params …

Pass a model to get its full lineage (ancestors and descendants):

get_model_lineage(file.path("models", "onecmt", "run003.mod"))

Hyperion Model Tree

ℹ️ Models: 3

  • models/onecmt/run002 Adding COV step, unfixing eps(2)
    • models/onecmt/run003 base, key | Base one-compartment oral absorption model
      • models/onecmt/run003b2 run003 with jittered params, exploring WT on V

Use from and to to filter the tree downward, upward, or to the slice between two models:

get_model_lineage(from = file.path("models", "onecmt", "run001.mod"))

Hyperion Model Tree

ℹ️ Models: 1

  • models/onecmt/run001 base | Base model 

get_model_lineage(to = file.path("models", "onecmt", "run003b1.mod"))

Hyperion Model Tree

ℹ️ Models: 1

  • models/onecmt/run003b1 Updating run003 to 003b1 with jittered params. … 

get_model_lineage(
  from = file.path("models", "onecmt", "run001.mod"),
  to   = file.path("models", "onecmt", "run003b1.mod")
)

Hyperion Model Tree

⚠️ Empty tree - no models found