## Introduction

Pmetrics data are either R6 objects loaded into memory or files, usually comma-separated (.csv). It is possible to use other separators, like the semicolon, by setting the appropriate argument with setPMoptions().

setPMoptions(sep = ";", dec = ",")
#changes field separator to ";" from default ","
#and decimal separator from "." to ","

Examples of programs that can save .csv files are any text editor (e.g. TextEdit on Mac, Notepad on Windows) or spreadsheet program (e.g. Excel). Please keep the number of characters in the file name ≤ 8.

## Data file use

R6

R6 Pmetrics introduces a new concept, the data object. The idea of this object is to represent a dataset that is going to be modeled/simulated. All its behaviour is represented by the class PM_data. This class allows datasets to be checked, plotted, written to disk and more. Use PM_data$new("filename") to create a PM_data() object by reading the file. #assume that data.csv is in the working directory data1 <- PM_data$new("data.csv")

You can also build an appropriate data frame in R and provide that as an argument to PM_data$new(). #assume df is data frame with at least these columns: #id, time, dose, out data1 <- PM_data$new(df)

Once you have created the PM_data() object, you never need to create it again during your R session. You also don’t have to bother copying the data file to the Runs folder each time you run the model.

Legacy

You must always have the the data file in the current working directory. You can manually copy it there from a previous run or some other folder or use the shortcut of providing a prior run number as an argument to NPrun() or ITrun().

#Run 1 - ensure that data.csv is in the working directory
NPrun("data.csv", "model.txt")

#run 2 - use the data from run 1 in this run
#note that the file model.txt still has to be copied
# into the working directory in this example
NPrun(data = 1, "model.txt")

## Data format

R6

PM_data$new() automatically calls PMcheck() so the data are validated as the data object is created. Legacy #### Read PMreadMatrix("filename", ...) reads filename and creates a PMmatrix object in R. However, unlike R6, it cannot be used to run a model. For that, you need to copy the file into the working directory each time, either yourself or by using the NPrun(data = 1, ...) shortcut, for example. #### Write PMwriteMatrix(data.frame, "filename", ...) writes an appropriate data frame as a new .csv file. It will first check the data.frame for errors via the PMcheck() function below, and writing will fail if errors are detected. This can be overridden with override=T. #### Standardize No standardizing occurs in Legacy as the file format must always be standard. To convert calendar dates and clock times to elapsed decimal time, use PMmatrixRelTime(). This function converts dates and clock times of specified formats into relative times for use in the NPAG, IT2B and Simulator engines. The output is used to create a data frame with relative times that can be saved as a new .csv file with PMwriteMatrix(), which in turn serves as input to a run. #### Validate PMcheck() will check a .csv file named filename or a PMmatrix data frame containing a previously loaded .csv file (the output of PMreadMatrix()) for errors which would cause the analysis to fail. If a model file is provided, and the data file has no errors, it will also check the model file for errors. If it finds errors, it will generate a new errors.xlsx file with all errors highlighted and commented so that you can find and correct them easily. PMcheck() is automatically called with every NPrun(), ITrun(), ERRrun(), and SIMrun() call, unless the nocheck = T argument is used. R6 Legacy The following functions are the same in either R6 or Legacy. • PMwrk2csv() This function will convert old-style, single-drug USC*PACK .wrk formatted files into Pmetrics data .csv files. • PMmb2csv() This function will convert USC*PACK .mb files into Pmetrics data .csv files. • NM2PM() Although the structure of Pmetrics data files is similar to NONMEM, there are some differences. This function attempts to automatically convert to Pmetrics format. It has been tested on several examples, but there are probably NONMEM files which will cause it to crash. Running PMcheck() afterwards is a good idea. ## Summary of R6 and Legacy Data Differences Function R6 Legacy Read data file PM_data$new() PMreadMatrix()
Check data file Embedded in PM_data$new() PMcheck() Write data file PM_data$write() PMwriteMatrix()
Convert calendar dates and clock times Embedded in PM_data\$new() PMmatrixReltime()
Convert from old USC*PACK .wrk format PMwrk2csv() PMwrk2csv()
Convert from NONMEM NM2PM() NM2PM()
Convert from old USC*PACK .mb format PMmb2csv() PMmb2csv()