Fill out evtools function set for dosing

[kylebaron]

Summary

These functions provide new functionality to (1) gives doses at steady state and (2) give additional doses. We also provide the user some of the "missing" api for working with these event objects in C++.

Note: working on this feature, I discovered behavior in #1229 that will need to be addressed in another work stream; it's a known issue now and will need some reimagining of how this in-model dosing is done.

All of the tests compare doses set up via the data set (or event object) and doses that are issued from inside the model. For each combination, there is a test for when the parent event is done "now" and another test when the parent dose is done "later".

New data members in evdata:

• ss
• ii
• addl

All of these items naturally initialize to 0. There is no new central functionality needed to handle these items; they just get passed into existing machinery.

New functions:

• ss() - advance the system to steady state prior to diving the dose
• ii() - specify the dose interval
• addl() - give additional doses
• amt() - set / reset the dose amount
• rate() - set / reset the infusion rate
• cmt()- set / reset the dose compartment

Existing functions:

• bolus() - bolus dose
• infuse() - start an infusion
• reset() - reset the system or reset and dose
• replace() - replace the amount in a compartment (evid 8)
• retime() - sets the time attribute and forces now to false
• now() - make an event happen "now"

The goal is to have a fairly complete set of functions to deal with these objects.

Example

library(mrgsolve)
#> 
#> Attaching package: 'mrgsolve'
#> The following object is masked from 'package:stats':
#> 
#>     filter
library(dplyr)
#> 
#> Attaching package: 'dplyr'
#> The following objects are masked from 'package:stats':
#> 
#>     filter, lag
#> The following objects are masked from 'package:base':
#> 
#>     intersect, setdiff, setequal, union

code <- '
$PLUGIN evtools autodec

$PARAM 
CL = 1, V = 25, KA = 1.3
Dose = 100, Ii = 24, End = 240, Ss = -1

$PKMODEL cmt = "A1,A2", depot = TRUE

$ERROR
if(NEWIND <= 1) {
  evt::ev dose = evt::bolus(Dose, 1);
  evt::ii(dose, Ii); 
  evt::addl(dose, (End/Ii));
  if(Ss > 0) evt::ss(dose, 1);
  self.push(dose);
}
'
mod <- mcode('foo', code)
#> Building foo ...
#> done.

Sensitivity analysis on dose, ii and addl

idata <- expand.idata(Dose = c(50, 100, 200), Ii = c(6, 12, 24), End = c(120, 240, 360))

out <- mrgsim(mod, idata = idata, end = 360, recover = "Dose,Ii,End", recsort = 3) 

plot(out, A2~time|factor(End)*factor(Ii))

Simulation at steady-state

idata <- expand.idata(Dose = 100, Ii = c(6, 12, 24), Ss = c(0,1), End = 240)

out <- mrgsim(mod, idata = idata, end = 360, recover = "Dose,Ii,Ss", recsort = 3) 

plot(out, A2~time|factor(Ss))

^{Created on 2024-09-03 with reprex v2.1.1}