Skip to contents

[Stable]

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

data

Data frame containing the data to be modeled

standard_data

Data 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

data

A 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.

dt

Pmetrics 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 the PM_data$standard_data field look correct. Other date/time formats are possible. See lubridate::parse_date_time() for these.

quiet

Quietly validate. Default is FALSE.

validate

Check for errors. Default is TRUE. Strongly recommended.

...

Arguments to be passed further

Details

Creation of a new PM_data objects from a file or a data frame. Data will be standardized and checked automatically to a fully specified, valid data object.


Method write()

Write data to file

Usage

PM_data$write(file_name, ...)

Arguments

file_name

A quoted name of the file to create with full path if not in the working directory.

...

Arguments passed to PMwriteMatrix

Details

Writes a delimited file (e.g. comma-separated) from the standard_data field


Method auc()

Calculate AUC

Usage

PM_data$auc(...)

Arguments

...

Arguments passed to makeAUC.

Details

See makeAUC.


Method nca()

Perform non-compartmental analysis

Usage

PM_data$nca(...)

Arguments

...

Arguments passed to makeNCA.

Details

See makeNCA.


Method plot()

Plot method

Usage

PM_data$plot(...)

Arguments

...

Arguments passed to plot.PM_data

Details

See plot.PMmatrix.


Method print()

Print method

Usage

PM_data$print(standard = F, viewer = T, ...)

Arguments

standard

Display the standardized data if TRUE. Default is FALSE.

viewer

Display the Viewer if TRUE. Default is TRUE.

...

Other arguments to print.data.frame. Only passed if viewer = FALSE.

Details

Displays the PM_data object in a variety of ways.


Method summary()

Summary method

Usage

PM_data$summary(...)

Arguments

...

Arguments passed to summary.PMmatrix.

Details

See summary.PMmatrix.


Method addEvent()

Add events to PM_data object

Usage

PM_data$addEvent(..., dt = NULL, quiet = FALSE, validate = FALSE)

Arguments

...

Column names and values.

dt

Pmetrics 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 the PM_data$standard_data field look correct. Other date/time formats are possible. See lubridate::parse_date_time() for these.

quiet

Quietly validate. Default is FALSE.

validate

Validate the new row or not. Default is FALSE as 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 set validate = TRUE for 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 addEvent and 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 addEvent with 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, because out wasn't in the original call and the next call contains a value for time, an out value of -1 will be added at time 144 and out will be set to NA for all the previous rows.

  • In contrast, the behavior is different if you omit time when your data object already has rows. In this case the arguments in the call to addEvent (without a value for time) 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 created dat object. Here, a duration of 0.5 hours will be added to every previous row in dat to create the new dat object, but no new row is added since there is no time associated 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)


Method clone()

The objects of this class are cloneable with this method.

Usage

PM_data$clone(deep = FALSE)

Arguments

deep

Whether to make a deep clone.

Examples


## ------------------------------------------------
## Method `PM_data$addEvent`
## ------------------------------------------------

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)