mapbayr (version 0.10.2)

obs_rows: Add observation lines to a dataset

Description

The obs_rows() function adds an one or several observation lines to a dataset provided as a proper data.frame or within a 'mrgsolve' model. Used in combination with adm_rows() and add_covariates(), it helps the creation of datasets in the proper format for simulations with 'mrgsolve' or parameter estimation with 'mapbayr', as explained in data_helpers.

Usage

obs_rows(x, ...)
# S3 method for data.frame
obs_rows(
  x,
  ID = NULL,
  time = NULL,
  evid = 0L,
  cmt,
  DV = NA_real_,
  mdv = NULL,
  .datehour = NULL,
  ...
)
# S3 method for missing
obs_rows(...)
# S3 method for mrgmod
obs_rows(x, cmt = NULL, DV = NA_real_, DVmet = NULL, ...)

Value

a data.frame, or a 'mrgsolve' model with a dataset in the @args$data slot (accessible with get_data()).

Arguments

x

either a data.frame or a 'mrgsolve' model object

...

additional columns

ID

subject ID (default is 1)

time

event time. Default is 0 if no previous events. Mind consistency with .datehour.

evid

event identification (default is 1 for administration, 0 for observation)

cmt

compartment (no default, except if [OBS] was tagged in the $CMT block in model code. See examples.)

DV

dependent value, i.e. observed concentration.

mdv

missing dependent value (default is 0 a non-missing concentration value to take into account for parameter estimation, 1 otherwise)

.datehour

a object of class POSIXct, a number or a character vector that can be passed to parse_datehour(). Using .datehour will update the value of time in the dataset, with units in hours. Mind consistency with the time argument.

DVmet

second observation at the same time (e.g. a metabolite, "DVmet") observed jointly with parent drug ("DV"). Works only if x is a 'mrgsolve' model where two [OBS] compartments were defined (see examples)

See Also

data_helpers

Examples

# Create a dataset from scratch
obs_rows(time = 12, DV = 0.12, cmt = 2)

# Pipe-friendly addition of observation record to a pre-existing dataset
library(magrittr)
obs_rows(time = 12, DV = 0.12, cmt = 2) %>%
  obs_rows(time = c(24, 36, 48), DV = c(0.34, 0.56, 0.78), mdv = c(0, 1, 0), cmt = 2)

# Inform times using the `.datehour` argument:
obs_rows(.datehour = "2020-01-01 11:11", DV = 0.12, cmt = 1) %>%
  obs_rows(.datehour = "2020-01-02 22:22", DV = 0.34, cmt = 1) %>%
  obs_rows(time = 48, DV = 0.56, cmt = 1)

# Start from a 'mrgsolve' model
library(mrgsolve)
house() %>%
  obs_rows(time = 12, DV = 0.12, cmt = 2) %>%
  obs_rows(time = c(24, 36, 48), DV = c(0.34, 0.56, 0.78), mdv = c(0, 1, 0), cmt = 2) %>%
  mrgsim()

# Default observation compartments
# Set default observation compartments in the code with `[OBS]`
model <- mcode("model", "
$CMT @annotated
DEPOT : Depot
CENTR : Central [OBS]
", compile = FALSE)
obs_cmt(model)

# Thus, no need to manually specify `cmt = 2` anymore.
model %>%
  obs_rows(time = 12, DV = 0.12) %>%
  obs_rows(time = c(24, 36, 48), DV = c(0.34, 0.56, 0.78), mdv = c(0, 1, 0)) %>%
  get_data()

# Automatic lines duplication if parent + metabolite defined in the model
model <- mcode("model", "
$CMT @annotated
DEPOT : Depot
CENTR : Central [OBS]
PERIPH : Periph
METABO : Metabo [OBS]
", compile = FALSE)
obs_cmt(model)

model %>%
  obs_rows(time = 12, DV = 0.12, DVmet = 120) %>%
  obs_rows(
    time = c(24, 36, 48), DV = c(0.34, 0.56, 0.78),
    mdv = c(0, 1, 0), DVmet = c(340, 560, 780)
  ) %>%
  get_data()