In AstraZeneca/blueprint: create models easily

BLUEPRINT

Create a model blueprint, using a consistent API across modeling platforms.

library(blueprint)
blueprint <- Blueprint$new("nonmem")

Blueprints are combined with templates (see below for specifics) to scaffold out model control streams.

There are default templates for nonmem and mrgsolve, however arbitrary user defined templates can be easily used as well. The first template is the compartmental template, which supports the various compartment models, eg 1/2 cmt iv/oral etc.

templates <- load_templates("nonmem")
models <- available_models("nonmem")

The specific template and model will need to be bound to the blueprint model to render, however this is dynamic, as to generate different model types easily.

Core Concepts

Blueprint provides a pipeline-based API for declaring the model components. In general, the nomenclature draws from a general terminology to NLMEM. Specifically, there are constants, parameters (thetas) and hierarchies (omega/sigma). These constants, parameters, and hierarchies are combined together to inform the model structure.

The required components for each piece are as minimal as possible, generally a value and a name, though this also is extended to incorporate other settings common, such as lower and upper bound, and whether the element should be fixed, comments (such as units).

parameters

basic declaration

cl <- parameter(1.5)
cl

full declaration

cl <- parameter(1.5, 
  "CL",
  lower_bound = 0, 
  upper_bound = 100,
  fixed = FALSE,
  link = "CL"
)
cl

hierarchies

hierarchies can either be diagonal or block elements. Diagonal elements are specified via omega_param and block elements via block. The hierarchical parameter is linked to a parameter via a name.

b1 <- block(0.04, 0.01, 0.09, param_names = c("CL", "V"))
b1

Information about the raw matrix, as well as the resultant structure is stored.

b1$matrix
cat(b1$value)

Helpers

In addition to the model structure, a number of helpers to track and inject other information required by the softwares are available.

• with_data - dataset to be modeled, can extract column names, calculations, etc
• from_path - path to data to inject into the input of a control stream.

Basic example

one_cmpt_iv <- blueprint %>% 
  # use the one cmt iv template
  use_template(templates$compartmental) %>%
  model_type(models$one_cmt_iv) %>%
  # add clearance and volume parameters
  parameters(CL = parameter(5,  
                    lower_bound = 0.01, 
                    upper_bound = 10),
         V = parameter(34, lower_bound = 0.1)) %>%
  with_data(head(Theoph)) %>%
  from_path("path/to/my_data.csv") 

one_cmpt_iv %>% render() %>% cat()

one_cmt_block <- one_cmpt_iv %>%
  hierarchies(b1 = block(0.04, 0.01, 0.09, param_names = c("CL", "V")))

one_cmt_block %>% render() %>% cat()

one_cmt_diag <- one_cmpt_iv %>%
  hierarchies(CL = 0.04, V = 0.09)

one_cmt_diag %>% render() %>% cat()

one_cmt_block %>%
  residual_error(ADD = 1) %>%
  render() %>% cat()
one_cmt_block %>%
  residual_error(ADD = 1, PROP = 0.1) %>%
  render() %>% cat()

Extending templates

One of the most powerful components of blueprint, is the fact that the built-in templates are just starting points, and can easily be extended.

bp <- Blueprint$new("nonmem")

In this case, a model has already been established, but would like to use blueprint to inject the parameter estimates

In this case, blueprint understands how to inject the theta and omega values, in the portion of the template below

{{#parameters}}
{{> theta}}
{{/parameters}}

{{#omegas}}
{{> omega}}
{{/omegas}}

bp$template <- "
$PROBLEM
$INPUT ... omitted for simplicity
$DATA ...omitted for simplicity
$SUBROUTINE ADVAN2 TRANS2

$PK
TVF1 = THETA(1)
F1 = TVF1*EXP(ETA(1))
TVALAG1 = THETA(2)
ALAG1 = TVALAG1*EXP(ETA(2))
TVKA = THETA(3)
KA = TVKA*EXP(ETA(3))
TVCL = THETA(4)
CL = TVCL*EXP(ETA(4))
TVV = THETA(5)
V = TVV*EXP(ETA(5))
S2 = V/1000

$ERROR
IPRED=FW=IPRED
; Specifications for M3 method
LLOQ = 1.0 ;LLOQ = 1 ng/mL
SD = SQRT(SIGMA(1,1))
DUM=( LLOQ-IPRED ) / SD ;Dummy variable defining distribution
CUMD=PHI(DUM);Cumulative distribution of DUM

IF(BLQ.EQ.0.OR.NPDE_MODE.EQ.1) THEN ; 0 for measured sample
F_FLAG=0
Y = IPRED * (1+EPS(1))
ENDIF

IF(BLQ.EQ.1.AND.NPDE_MODE.EQ.0) THEN
F_FLAG=1
Y=CUMD
MDVRES=1
ENDIF

IF(BLQ.EQ.1) DV_LOQ=LLOQ

$THETA
{{#parameters}}
{{> theta}}
{{/parameters}}

{{#omegas}}
{{> omega}}
{{/omegas}}

$EST ...omitted for simplicity
"

bp %>% parameters(
  F1 = parameter(0.8, upper_bound = 1),
  ALAG1 = parameter(0.5, lower_bound = 0, comment = "lag time; hours"),
  KA = parameter(1, comment = "1/hr"),
  CL = parameter(1.4, lower_bound = 0.1, comment = "L/hr"),
  V = parameter(32.5, lower_bound = 0.1, comment = "L")
) %>%
  hierarchies(F1 = 0.1,
              ALAG1 = 0.1,
              KA = 0.1,
              CL_V = block(0.1, 0.01, 0.1,
                           param_names = c("CL", "V"))) %>%
  render() %>% cat

This templating leverages the whisker library to do the templating injection.

Eventual extensions

even more standard templates

knitr::opts_chunk$set(eval = FALSE)

query language sugar for templates

blueprint %>%
  ode_model(cmt = 1, depot = 1) %>%
  parameterize("CL") 

• shiny app to dynamically create control streams via GUI
• expanding support for a generic ODE language interface
• supporting more nonmem features

AstraZeneca/blueprint documentation built on May 17, 2019, 11:32 a.m.