[Stable]

Follows PsN coding conventions to add covariates into a model. The advantage is no need to create a .scm file, just directly modify the NONMEM control file contents. This function is used by covariate_step_tibble() for stepwise covariate model development.

add_cov(
  ctl,
  param,
  cov,
  state = 2,
  continuous = TRUE,
  time_varying,
  additional_state_text = list(),
  id_var = "ID",
  force = FALSE,
  force_TV_var = FALSE,
  init,
  lower,
  upper
)

remove_cov(
  ctl,
  param,
  cov,
  state = 2,
  continuous = TRUE,
  time_varying,
  id_var = "ID"
)

Arguments

ctl

An nm object or an object coercible to ctl_list.

param

Character. Name of parameter.

cov

Character. Name of covariate.

state

Numeric or character. Number or name of state (see details).

continuous

Logical (default = TRUE). Is covariate continuous?

time_varying

Optional logical. is the covariate time varying?

additional_state_text

Optional character (default = empty). Custom state variable to be passed to param_cov_text.

id_var

Character (default = "ID"). Needed if time_varying is missing.

force

Logical (default = `FALSE``). Force covariate in even if missing values found.

force_TV_var

Logical (default = FALSE). Force covariates only on TV notation parameters.

init

Optional numeric/character vector. Initial estimate of additional parameters.

lower

Optional numeric/character vector. lower bound of additional parameters.

upper

Optional numeric/character vector. Upper bound of additional parameters.

Value

An nm object with modified ctl_contents field.

Details

Available states:

"2" or "linear"

PARCOV= ( 1 + THETA(1)*(COV -median))

"3" or "hockey-stick"

IF(COV.LE.median) PARCOV = ( 1 + THETA(1)*(COV - median)) IF(COV.GT.median) PARCOV = ( 1 + THETA(2)*(COV - median))

"4" or "exponential"

PARCOV= EXP(THETA(1)*(COV - median))

"5" or "power"

PARCOV= ((COV/median)**THETA(1))

"power1"

PARCOV= ((COV/median))

"power0.75"

PARCOV= ((COV/median)**0.75)

"6" or "log-linear"

PARCOV= ( 1 + THETA(1)*(LOG(COV) - log(median)))

remove_cov only works with covariates added with add_cov.

Examples


# create example object m1 from package demo files
exdir <- system.file("extdata", "examples", "theopp", package = "NMproject")
m1 <- new_nm(run_id = "m1", 
             based_on = file.path(exdir, "Models", "ADVAN2.mod"),
             data_path = file.path(exdir, "SourceData", "THEOPP.csv"))

temp_data_file <- paste0(tempfile(), ".csv")

## dataset has missing WTs so create a new one and assign this to the run
input_data(m1) %>% 
  dplyr::group_by(ID) %>%
  dplyr::mutate(WT = na.omit(WT)) %>%
  write_derived_data(temp_data_file)
#> written: 
#> /var/folders/24/8k48jl6d249_n_qfxwsl6xvm0000gn/T//RtmpViX25W/filef7271b2af61.RDS
#> /var/folders/24/8k48jl6d249_n_qfxwsl6xvm0000gn/T//RtmpViX25W/filef7271b2af61.csv
  
m1 <- m1 %>% data_path(temp_data_file)
 
m1WT <- m1 %>% child("m1WT") %>%
  add_cov(param = "V", cov = "WT", state = "power")

m1 %>% dollar("PK")
#> $`execute.Models/m1`
#>   1| $PK
#>   2| 
#>   3| TVKA=EXP(THETA(1))
#>   4| MU_1=LOG(TVKA)
#>   5| KA = EXP(MU_1+ETA(1))
#>   6| 
#>   7| TVK=EXP(THETA(2))
#>   8| MU_2=LOG(TVK)
#>   9| K = EXP(MU_2+ETA(2))
#>  10| 
#>  11| TVV=EXP(THETA(3))
#>  12| MU_3=LOG(TVV)
#>  13| V = EXP(MU_3+ETA(3))
#>  14| 
#>  15| CL = K*V
#>  16| 
#>  17| S2 = V
#>  18| 
#> 
m1WT %>% dollar("PK")  ## notice SCM style code added
#> $`execute.Models/m1WT`
#>   1| $PK
#>   2| 
#>   3| ;;; TVVWT-DEFINITION START
#>   4| TVVWT= ((WT/70.5)**THETA(4))
#>   5| ;;; TVVWT-DEFINITION END
#>   6| 
#>   7| ;;; TVV-RELATION START
#>   8| TVVCOV=TVVWT
#>   9| ;;; TVV-RELATION END
#>  10| 
#>  11| TVKA=EXP(THETA(1))
#>  12| MU_1=LOG(TVKA)
#>  13| KA = EXP(MU_1+ETA(1))
#>  14| 
#>  15| TVK=EXP(THETA(2))
#>  16| MU_2=LOG(TVK)
#>  17| K = EXP(MU_2+ETA(2))
#>  18| 
#>  19| TVV=EXP(THETA(3))
#>  20| 
#>  21| TVV = TVVCOV*TVV
#>  22| MU_3=LOG(TVV)
#>  23| V = EXP(MU_3+ETA(3))
#>  24| 
#>  25| CL = K*V
#>  26| 
#>  27| S2 = V
#>  28| 
#> 

nm_diff(m1WT)
#> < old_ctl                                         
#> > new_ctl                                         
#> @@ 28,4 / 28,12 @@                                
#>   $PK                                             
#>                                                   
#> > ;;; TVVWT-DEFINITION START                      
#> > TVVWT= ((WT/70.5)**THETA(4))                    
#> > ;;; TVVWT-DEFINITION END                        
#> >                                                 
#> > ;;; TVV-RELATION START                          
#> > TVVCOV=TVVWT                                    
#> > ;;; TVV-RELATION END                            
#> >                                                 
#>   TVKA=EXP(THETA(1))                              
#>   MU_1=LOG(TVKA)                                  
#> @@ 37,4 / 45,6 @@                                 
#>                                                   
#>   TVV=EXP(THETA(3))                               
#> >                                                 
#> > TVV = TVVCOV*TVV                                
#>   MU_3=LOG(TVV)                                   
#>   V = EXP(MU_3+ETA(3))                            
#> @@ 58,4 / 68,5 @@                                 
#>   .....           ; V  ; L ; LOG                  
#>                                                   
#> > $THETA  (-1,0.8,5) ; TVVWTpower                 
#>   $OMEGA                                          
#>   0.1                               ; IIV_KA ; LOG

if (FALSE) {
run_nm(c(m1, m1WT))
rr(c(m1, m1WT))
summary_wide(c(m1, m1WT)) 
}

unlink(temp_data_file)


# create example object m1 from package demo files
exdir <- system.file("extdata", "examples", "theopp", package = "NMproject")
m1 <- new_nm(run_id = "m1", 
             based_on = file.path(exdir, "Models", "ADVAN2.mod"),
             data_path = file.path(exdir, "SourceData", "THEOPP.csv"))

temp_data_file <- paste0(tempfile(), ".csv")

## dataset has missing WTs so create a new one and assign this to the run
input_data(m1) %>% 
  dplyr::group_by(ID) %>%
  dplyr::mutate(WT = na.omit(WT)) %>%
  write_derived_data(temp_data_file)
#> written: 
#> /var/folders/24/8k48jl6d249_n_qfxwsl6xvm0000gn/T//RtmpViX25W/filef72a184398.RDS
#> /var/folders/24/8k48jl6d249_n_qfxwsl6xvm0000gn/T//RtmpViX25W/filef72a184398.csv
  
m1 <- m1 %>% data_path(temp_data_file)
 
m1WT <- m1 %>% child("m1WT") %>%
  add_cov(param = "V", cov = "WT", state = "power")

m1 %>% dollar("PK")
#> $`execute.Models/m1`
#>   1| $PK
#>   2| 
#>   3| TVKA=EXP(THETA(1))
#>   4| MU_1=LOG(TVKA)
#>   5| KA = EXP(MU_1+ETA(1))
#>   6| 
#>   7| TVK=EXP(THETA(2))
#>   8| MU_2=LOG(TVK)
#>   9| K = EXP(MU_2+ETA(2))
#>  10| 
#>  11| TVV=EXP(THETA(3))
#>  12| MU_3=LOG(TVV)
#>  13| V = EXP(MU_3+ETA(3))
#>  14| 
#>  15| CL = K*V
#>  16| 
#>  17| S2 = V
#>  18| 
#> 
m1WT %>% dollar("PK")  ## notice SCM style code added
#> $`execute.Models/m1WT`
#>   1| $PK
#>   2| 
#>   3| ;;; TVVWT-DEFINITION START
#>   4| TVVWT= ((WT/70.5)**THETA(4))
#>   5| ;;; TVVWT-DEFINITION END
#>   6| 
#>   7| ;;; TVV-RELATION START
#>   8| TVVCOV=TVVWT
#>   9| ;;; TVV-RELATION END
#>  10| 
#>  11| TVKA=EXP(THETA(1))
#>  12| MU_1=LOG(TVKA)
#>  13| KA = EXP(MU_1+ETA(1))
#>  14| 
#>  15| TVK=EXP(THETA(2))
#>  16| MU_2=LOG(TVK)
#>  17| K = EXP(MU_2+ETA(2))
#>  18| 
#>  19| TVV=EXP(THETA(3))
#>  20| 
#>  21| TVV = TVVCOV*TVV
#>  22| MU_3=LOG(TVV)
#>  23| V = EXP(MU_3+ETA(3))
#>  24| 
#>  25| CL = K*V
#>  26| 
#>  27| S2 = V
#>  28| 
#> 

## reverse this by removing WT

m1noWT <- m1WT %>% child("m1noWT") %>%
  remove_cov(param = "V", cov = "WT") 
  
m1noWT %>% dollar("PK")
#> $`execute.Models/m1noWT`
#>   1| $PK
#>   2| 
#>   3| 
#>   4| 
#>   5| TVKA=EXP(THETA(1))
#>   6| MU_1=LOG(TVKA)
#>   7| KA = EXP(MU_1+ETA(1))
#>   8| 
#>   9| TVK=EXP(THETA(2))
#>  10| MU_2=LOG(TVK)
#>  11| K = EXP(MU_2+ETA(2))
#>  12| 
#>  13| TVV=EXP(THETA(3))
#>  14| 
#>  15| MU_3=LOG(TVV)
#>  16| V = EXP(MU_3+ETA(3))
#>  17| 
#>  18| CL = K*V
#>  19| 
#>  20| S2 = V
#>  21| 
#> 
m1noWT %>% dollar("THETA")
#> $`execute.Models/m1noWT`
#>   1| $THETA
#>   2| .....          	; KA ; h-1 ; LOG
#>   3| .....          	; K  ; h-1 ; LOG
#>   4| .....          	; V  ; L ; LOG
#>   5| 
#> 

unlink(temp_data_file)