R: Make addl doses explicit in an event object or data set

realize_addl {mrgsolve} | R Documentation

## Make addl doses explicit in an event object or data set

### Description

When doses are scheduled with `ii` and `addl`, the object is expanded to include one record for every dose. In the result, no record with have `ii` or `addl` set to non-zero value.

### Usage

    realize_addl(x, ...)

    ## S3 method for class 'data.frame'
    realize_addl(
      x,
      warn = FALSE,
      mark_new = FALSE,
      fill = c("inherit", "na", "locf"),
      ...
    )

    ## S3 method for class 'ev'
    realize_addl(x, ...)

### Arguments

`x` | a `data_set` data frame or an event object (see details)
`...` | not used
`warn` | if `TRUE` a warning is issued if no `ADDL` or `addl` column is found
`mark_new` | if `TRUE`, a flag is added to indicate new columns
`fill` | specifies how to handle non-dose related data columns in new data set records; this option is critical when handling data sets with time-varying, non-dose-related data items; see details

### Details

If no `addl` column is found the data frame is returned and a warning is issued if `warn` is true. If `ii`, `time`, or `evid` are missing, an error is generated.

If a grouped data.frame (via `dplyr::group_by()`) is passed, it will be ungrouped.

Use caution when passing in data that has non-dose-related data columns that vary within a subject and pay special attention to the `fill` argument. By definition, `realize_addl` will add new rows to your data frame and it is not obvious how the non-dose-related data should be handled in these new rows. When `inherit` is chosen, the new records have non-dose-related data that is identical to the originating dose record. This should be fine when these data items are not varying with time, but will present a problem when the data are varying with time. When `locf` is chosen, the missing data are filled in with `NA` and an last observation carry forward operation is applied to every column in the data set. This may not be what you want if you already had missing values in the input data set and want to preserve that missingness. When `na` is chosen, the missing data are filled in with `NA` and no `locf` operation is applied. But note that these missing values may be problematic for a mrgsolve simulation run. If you have any time-varying columns or missing data in your data set, be sure to check that the output from this function is what you were expecting.

### Value

A `data_set` data.frame or event object, consistent with the type of `x`. The `ii` and `addl` columns will all be set to zero. The result is always ungrouped.

### Examples

    e <- ev(amt = 100, ii = 12, addl = 3)

    realize_addl(e)

    a <- ev(amt = 100, ii = 12, addl = 2, WT = 69)
    b <- ev(amt = 200, ii = 24, addl = 2, WT = 70)
    c <- ev(amt =  50, ii =  6, addl = 2, WT = 71)

    e <- ev_seq(a,b,c)
    realize_addl(e, mark_new = TRUE)

[Package mrgsolve version 1.0.4 Index]