Adds simulation events to all subjects in a data set. Copies over columns that are not varying at subject level (i.e. non-variying covariates). Can add simulation events relative to previous dosing time.
Usage
addEVID2(
data,
TIME,
TAPD,
CMT,
EVID,
DV,
col.id = "ID",
args.NMexpandDoses,
unique = TRUE,
as.fun,
doses,
time.sim
)Arguments
- data
Nonmem-style data set. If using `TAPD` an `EVID` column must contain 1 for dosing records.
- TIME
A numerical vector with simulation times. Can also be a data.frame in which case it must contain a `TIME` column and is merged with `data`.
- TAPD
A numerical vector with simulation times, relative to previous dose. When this is used, `data` must contain rows with `EVID=1` events and a `TIME` column. `TAPD` can also be a data.frame in which case it must contain a `TAPD` column and is merged with `data`.
- CMT
The compartment in which to insert the EVID=2 records. Required if `CMT` is a column in `data`. If longer than one, the records will be repeated in all the specified compartments. If a data.frame, covariates can be specified.
- EVID
The value to put in the `EVID` column for the created rows. Default is 2 but 0 may be prefered even for simulation.
- DV
Optionally provide a single value to be assigned to the `DV` column. The default is to assign nothing which will result in `NA` as samples are stacked (`rbind`) with `data`. If you assign a different value in `DV`, the default value of `EVID` changes to `0`, and `MDV` will be `0` instead of `1`. An example where this is useful is when generating datasets for `$DESIGN` where `DV=0` is often used.
- col.id
The name of the column in `data` that holds the unique subject identifier.
- args.NMexpandDoses
Only relevant - and likely not needed - if data contains ADDL and II columns. If those columns are included, `addEVID2()` will use `NMdata::NMexpanDoses()` to evaluate the time of each dose. Other than the `data` argument, `addEVID2()` relies on the default `NMexpanDoses()` argument values. If this is insufficient, you can specify other argument values in a list, or you can call `NMdata::NMexpanDoses()` manually before calling `addEVID2()`.
- unique
If `TRUE` (default), events are reduced to unique time points before insertion. Sometimes, it's easier to combine sequences of time points that overlap (maybe across `TIME` and `TAPD`), and let `addEVID2()` clean them. If you want to keep your duplicated events, use `unique=FALSE`.
- as.fun
The default is to return data as a `data.frame`. Pass a function (say `tibble::as_tibble`) in as.fun to convert to something else. If data.tables are wanted, use `as.fun="data.table"`. The default can be configured using `NMdataConf()`.
- doses
Deprecated. Use `data`.
- time.sim
Deprecated. Use `TIME`.
Details
The resulting data set is ordered by ID, TIME, and EVID. You may have to reorder for your specific needs.
Examples
(doses1 <- NMcreateDoses(TIME=c(0,12,24,36),AMT=c(2,1)))
#> ID TIME EVID CMT AMT MDV
#> 1 1 0 1 1 2 1
#> 2 1 12 1 1 1 1
#> 3 1 24 1 1 1 1
#> 4 1 36 1 1 1 1
addEVID2(doses1,TIME=seq(0,28,by=4),CMT=2)
#> ID TIME EVID CMT AMT MDV
#> 1 1 0 1 1 2 1
#> 2 1 0 2 2 NA 1
#> 3 1 4 2 2 NA 1
#> 4 1 8 2 2 NA 1
#> 5 1 12 1 1 1 1
#> 6 1 12 2 2 NA 1
#> 7 1 16 2 2 NA 1
#> 8 1 20 2 2 NA 1
#> 9 1 24 1 1 1 1
#> 10 1 24 2 2 NA 1
#> 11 1 28 2 2 NA 1
#> 12 1 36 1 1 1 1
## two named compartments
dt.doses <- NMcreateDoses(TIME=c(0,12),AMT=10,CMT=1)
seq.time <- c(0,4,12,24)
dt.cmt <- data.frame(CMT=c(2,3),analyte=c("parent","metabolite"))
res <- addEVID2(dt.doses,TIME=seq.time,CMT=dt.cmt)
## Separate sampling schemes depending on covariate values
dt.doses <- NMcreateDoses(TIME=data.frame(regimen=c("SD","MD","MD"),TIME=c(0,0,12)),AMT=10,CMT=1)
seq.time.sd <- data.frame(regimen="SD",TIME=seq(0,6))
seq.time.md <- data.frame(regimen="MD",TIME=c(0,4,12,24))
seq.time <- rbind(seq.time.sd,seq.time.md)
addEVID2(dt.doses,TIME=seq.time,CMT=2)
#> ID TIME EVID CMT AMT MDV regimen
#> 1 1 0 1 1 10 1 SD
#> 2 1 0 2 2 NA 1 SD
#> 3 1 1 2 2 NA 1 SD
#> 4 1 2 2 2 NA 1 SD
#> 5 1 3 2 2 NA 1 SD
#> 6 1 4 2 2 NA 1 SD
#> 7 1 5 2 2 NA 1 SD
#> 8 1 6 2 2 NA 1 SD
#> 9 2 0 1 1 10 1 MD
#> 10 2 0 2 2 NA 1 MD
#> 11 2 4 2 2 NA 1 MD
#> 12 2 12 1 1 10 1 MD
#> 13 2 12 2 2 NA 1 MD
#> 14 2 24 2 2 NA 1 MD
## an observed sample scheme and additional simulation times
df.doses <- NMcreateDoses(TIME=0,AMT=50,addl=list(ADDL=2,II=24))
dense <- c(seq(1,3,by=.1),4:6,seq(8,12,by=4),18,24)
trough <- seq(0,3*24,by=24)
sim.extra <- seq(0,(24*3),by=2)
time.all <- c(dense,dense+24*3,trough,sim.extra)
time.all <- sort(unique(time.all))
dt.sample <- data.frame(TIME=time.all)
dt.sample$isobs <- as.numeric(dt.sample$TIME%in%c(dense,trough))
dat.sim <- addEVID2(dt.doses,TIME=dt.sample,CMT=2)
## TAPD - time after previous dose
df.doses <- NMcreateDoses(TIME=c(0,12),AMT=10,CMT=1)
seq.time <- c(0,4,12,24)
addEVID2(df.doses,TAPD=seq.time,CMT=2)
#> ID TIME EVID CMT AMT MDV TAPD
#> 1 1 0 1 1 10 1 NA
#> 2 1 0 2 2 NA 1 0
#> 3 1 4 2 2 NA 1 4
#> 4 1 12 1 1 10 1 NA
#> 5 1 12 2 2 NA 1 0
#> 6 1 16 2 2 NA 1 4
#> 7 1 24 2 2 NA 1 12
#> 8 1 36 2 2 NA 1 24
## TIME and TAPD
df.doses <- NMcreateDoses(TIME=c(0,12),AMT=10,CMT=1)
seq.time <- c(0,4,12,24)
addEVID2(df.doses,TIME=seq.time,TAPD=3,CMT=2)
#> ID TIME EVID CMT AMT MDV TAPD
#> 1 1 0 1 1 10 1 NA
#> 2 1 0 2 2 NA 1 NA
#> 3 1 3 2 2 NA 1 3
#> 4 1 4 2 2 NA 1 NA
#> 5 1 12 1 1 10 1 NA
#> 6 1 12 2 2 NA 1 NA
#> 7 1 15 2 2 NA 1 3
#> 8 1 24 2 2 NA 1 NA
## Using a custom DV value affects EVID and MDV
df.doses <- NMcreateDoses(TIME=c(0,12),AMT=10,CMT=1)
seq.time <- c(4)
addEVID2(df.doses,TAPD=seq.time,CMT=2,DV=0)
#> ID TIME EVID CMT AMT MDV TAPD DV
#> 1 1 0 1 1 10 1 NA NA
#> 2 1 4 0 2 NA 0 4 0
#> 3 1 12 1 1 10 1 NA NA
#> 4 1 16 0 2 NA 0 4 0