![[Stable]](figures/lifecycle-stable.svg)
PM_data R6 objects containing raw, standardized and valid data, and methods to process the data
Details
PM_data objects are passed to PM_fit objects to initiate a
population analysis. The object is created by reading a delimited file in
the current working directory. The data will be transformed into the standard
format which is the same for all engines, with a report of any assumptions
that were necessary to standardize the data. PMcheck is called
on the standard data to evaluate for errors. If dates and times are converted
to relative decimal times in the standard data, automatic detection of the correct
format will be attempted using lubridate::parse_date_time(). In the case of failure
due to an unusual format, use the 'dt' argument to specify the correct format in your
data. In the case of successful automatic detection, the format used will be
included in the standardization report generated upon creation of a new PM_data
object. Check carefully to make sure the correct format was chosen. Note that if
your clock times did not include seconds, they were appended as ":00" to the end
of each time and will appear that way in the copy of the original data.
There are a number of methods defined for a PM_data object, including to write the standard data back to a file for future use, to summarize and to plot the object, to conduct a non-compartmental analysis on the raw data using makeNCA, to calculate an AUC using makeAUC, and to add event rows, which is particularly useful for making simulation templates on the fly.
Public fields
dataData frame containing the data to be modeled
standard_dataData frame containing standardized version of the data
Methods
Method new()
Create new data object
Usage
PM_data$new(data = NULL, dt = NULL, quiet = FALSE, validate = TRUE)Arguments
dataA quoted name of a file with full path if not in the working directory, or an unquoted name of a data frame in the current R environment.
dtPmetrics will try a variety of date/time formats. If all 16 of them fail, use this parameter to specify the correct format as a character vector whose first element is date format and second is time. Use the following abbreviations:
Y = 4 digit year
y = 2 digit year
m = decimal month (1, 2, ..., 12)
d = decimal day (1, 2, ..., 31)
H = hours (0-23)
M = minutes (0-59) Example:
format = c("myd", "mh"). Not one of the tried combinations! Always check to make sure that dates/times were parsed correctly and the relative times in thePM_data$standard_datafield look correct. Other date/time formats are possible. Seelubridate::parse_date_time()for these.
quietQuietly validate. Default is
FALSE.validateCheck for errors. Default is
TRUE. Strongly recommended....Arguments to be passed further
Method write()
Write data to file
Arguments
file_nameA quoted name of the file to create with full path if not in the working directory.
...Arguments passed to PMwriteMatrix
Method nca()
Perform non-compartmental analysis
Arguments
...Arguments passed to makeNCA.
Details
See makeNCA.
Method print()
Print method
Arguments
standardDisplay the standardized data if
TRUE. Default isFALSE.viewerDisplay the Viewer if
TRUE. Default isTRUE....Other arguments to print.data.frame. Only passed if
viewer = FALSE.
Method summary()
Summary method
Arguments
...Arguments passed to summary.PMmatrix.
Details
See summary.PMmatrix.
Method addEvent()
Add events to PM_data object
Arguments
...Column names and values.
dtPmetrics will try a variety of date/time formats. If all 16 of them fail, use this parameter to specify the correct format as a character vector whose first element is date format and second is time. Use the following abbreviations:
Y = 4 digit year
y = 2 digit year
m = decimal month (1, 2, ..., 12)
d = decimal day (1, 2, ..., 31)
H = hours (0-23)
M = minutes (0-59) Example:
format = c("myd", "mh"). Not one of the tried combinations! Always check to make sure that dates/times were parsed correctly and the relative times in thePM_data$standard_datafield look correct. Other date/time formats are possible. Seelubridate::parse_date_time()for these.
quietQuietly validate. Default is
FALSE.validateValidate the new row or not. Default is
FALSEas a new row added to a blank will result in a one-row data object, which is invalid. Also, only one event type (dose or observation) should be added at a time, so if the new object contains only doses while building, this would cause an error. You should setvalidate = TRUEfor the final addition.
Details
Add lines to a PM_data object by supplying named columns and values.
ID is always required. Time is handled differently depending on
the sequence of addEvent calls (see Chaining below).
It is required for the first call to
addEventand should be 0. For example: For example:dat <- PM_data$new()$addEvent(id = 1, time = 0, dose = 100, addl = 5, ii = 24)For subsequent calls to
addEventwith specific times it should be included. For example:dat <- PM_data$new()$addEvent(id = 1, time = 0, dose = 100, addl = 5, ii = 24)$addEvent(id = 1, time = 144, out = -1)Here, becauseoutwasn't in the original call and the next call contains a value fortime, anoutvalue of -1 will be added at time 144 andoutwill be set toNAfor all the previous rows.In contrast, the behavior is different if you omit
timewhen your data object already has rows. In this case the arguments in the call toaddEvent(without a value fortime) will add those arguments as columns in the prior data with the specified value or replace values in those columns if they already exist. Be sure this is what you want. For example, building on the prior example:dat$addEvent(id = 1, dur = 0.5). Note that we can chain to the previously createddatobject. Here, a duration of 0.5 hours will be added to every previous row indatto create the newdatobject, but no new row is added since there is notimeassociated with it.
Adding covariates is supported, but since valid subject records in Pmetrics
with covariates must contain non-missing values at time 0, covariates should
be included with the first call to $addEvent().
As we have seen in the examples above, ADDL and II are supported.
Chaining Multiple $addEvent() calls can be chained with PM_data$new()
to create a blank data object and then add rows.
This can be particularly useful for creating simulation templates.
See the example.
Examples
PM_data$new()$addEvent(id = 1, time = 0, dose = 100, addl = 4, ii = 12,
out = NA, wt = 75)$addEvent(id = 1, time = 60, out = -1)