Software engines
There are three main software engines that Pmetrics controls.
IT2B is the ITerative 2-stage Bayesian parametric population PK modeling program. It is generally used to estimate parameter ranges to pass to NPAG. It will estimate values for population model parameters under the assumption that the underlying distributions of those values are normal or transformed to normal, e.g. log normal.
NPAG is the Non-parametric Adaptive Grid software. It will create a non-parametric population model consisting of discrete support points, each with a set of estimates for all parameters in the model plus an associated probability (weight) of that set of estimates. There can be at most one point for each subject in the study population. There is no need for any assumption about the underlying distribution of model parameter values.
The Simulator is a semi-parametric Monte Carlo simulation software program that can use the output of IT2B or NPAG to build randomly generated response profiles (e.g. time-concentration curves) for a given population model, parameter estimates, and data input. Simulation from a non-parametric joint density model, i.e. NPAG output, is possible, with each point serving as the mean of a multivariate normal distribution, weighted according to the weight of the point. The covariance matrix of the entire set of support points is divided equally among the points for the purposes of simulation.
Pmetrics control functions
R6
Pmetrics usesPM_data() to create data objects,
PM_model() to create model objects, and
PM_fit() to create objects that combine the model with the
data, ready to be run (fitted), generating probability distributions for
primary model parameters. These are extensively documented within R by
using the help(command) or ?command
syntax.
These functions replace the following Legacy functions:
ITrun(), ERRrun(), NPrun(),
although all Legacy functions are still supported for users who are
accustomed to them.
Invoking the simulator in R6 becomes a method attached to
PM_result() objects or by using PM_sim$run()
for models, parameter value probability distributions and template data
not derived from a previous fit, e.g. when lifted from an article.
Legacy
Pmetrics has groups of R functions named logically to run each of
these programs and to extract the output. Again, these are extensively
documented within R by using the help(command) or
?command syntax.
Run functions
R6
Once a PM_fit() object is created, which combines a
model with a data file, it can be run by using the syntax
$run() to access the appropriate function defined for the
PM_fit() object.
fit1 <- PM_fit$new(model, data)
fit1$run(options)R6 Legacy
For IT2B and NPAG, the “run” functions generate batch files, which
when executed, launch the software programs to do the analysis.
$run(engine="err") or ERRrun() is a special
implementation of IT2B designed to estimate the assay error polynomial
coefficients from the data, when they cannot be calculated from assay
validation data (using makeErrorPoly()) supplied by the
analytical laboratory. The batch files contain all the information
necessary to complete a run, tidy the output into a date/time stamped
directory with meaningful subdirectories, extract the information,
generate a report, and a saved Rdata file of parsed output which can be
quickly and easily loaded into R. On Mac (Unix) and Linux systems, the
batch file automatically launches in a Terminal window. Prior to v1.9,
on Windows systems, the batch file was launched manually, but as of
v1.9, this manual step is no longer necessary. The execution of the
program to do the actual model parameter estimation is independent of R,
so that the user is free to use R for other purposes.
R6
For the Simulator, the $sim method for a
PM_result object will execute the program directly within R
and return a PM_sim object.
run1 <- PM_load(1)
sim1 <- run1$sim(data = "new.csv")The first line loads previous results of run 1 into a PM_result object called run1. The second line uses model and prior in run1 with new data template.
An equivalent method is to run a new PM_sim() directly
with PM_sim$run(). It also returns a PM_sim()
object, i.e. there is no longer any need to run
SIMparse().
sim1 <- PM_sim$run(poppar = list(...), model = "model.txt", data = "new.csv") See vignette("simulation") for details on specifying
poppar this way.
Legacy
To run the simulator in legacy mode, use SIMrun().
Results are saved to the hard drive in the working directory, and can be
read with SIMparse() as described below.
SIMrun(...)The above command, with the appropriate arguments to replace “…”,
will execute a simulation and save the results to the hard drive. The
arguments are all documented in ?SIMrun. By default, these
files will be called “simoutX.csv”, where “X” will be sequential numbers
1, 2, 3, … corresponding to the subject number in the template data
file. These “simout” files are read by SIMparse()
below.
Parse functions
R6 Legacy
For all programs, the “parse” functions will extract the primary output from the program into meaningful R data objects. For IT2B and NPAG in either R6 or Legacy modes, this is done automatically at the end of a successful run, and the objects are saved in the output subdirectory as IT2Bout.Rdata or NPAGout.Rdata, respectively. The parse functions are not generally necessary for the user to access.
R6
For the simulator the results are returned automatically to the
object assigned to contain the output of the simulation,
e.g. sim1 below.
sim1 <- PM_result$sim(...)As mentioned above, there is no longer any need to use the
SIMparse() Legacy function described below, because the
SIMrun() and SIMparse() Legacy functions are
combined within the $sim() method for
PM_result() objects or the $run() method for
PM_sim() objects.
Legacy
After running the simulator with SIMrun(), the results
are saved to files in the working directory. They can be retrieved using
SIMparse(). See ?SIMparse for options,
including use of wildcards and combining simulation output files.
simdata <- SIMparse("simout1.txt")Saving functions
R6
The Pmetrics R6 objects PM_fit(),
PM_result(), PM_sim(),
PM_valid(), and PM_pta() all have a
$save() method. This method saves the object to the hard
drive in the current working directory by default. The format is .rds
which is a binary format used by R to save individual objects. The
purpose of the $save() method is to enable retrieval of the
object at a later time.
Legacy
Objects created that are attached to a particular run can be
identified by using the same suffix number as the run.
PMsave() can add these attached objects to the .Rdata file
for that run, which is loaded with PMload().
In the above example, sim.2 will be added to the .Rdata
file for future retrieval with PMload(2).
Loading functions
R6
After a successful IT2B or NPAG run, PM_load() creates a
PM_result() object rather than loading run results into the
current environment and suffixed with the run number as for legacy
mode.
res1 <- PM_load(1)
res1$op$plot()PM_result(), PM_fit(),
PM_sim(), PM_valid(), and
PM_pta() all have a $load() method that takes
as its only argument the full or relative path (if not in the working
directory) and name of an .rds file created by the corresponding
$save() method.
sim1 <- PM_sim$load("sim.rds")Legacy
For IT2B and NPAG, the PMload() function can be used to
load the .Rdata file after a successful run. Objects will be loaded into
the current environment in R and suffixed with “.run”, where “run” is
the run number.
For simulations, SIMparse(), described above, combines
the parsing and loading functions.
sim.2 <- SIMparse("simout1.txt")Report generation
R6 Legacy
The PMreport() function is automatically run at the end
of a successful NPAG and IT2B run, and it will generate an HTML page
with summaries of the run, as well as the .Rdata files and other
objects. The default browser will be automatically launched for viewing
of the HTML report page.
Other functions
R6 Legacy
Within Pmetrics there are also functions to manipulate data .csv files and process and plot extracted data.
Data manipulation
| 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() |
Model selection and diagnostics
| Function | R6 | Legacy |
|---|---|---|
| Compare models | PM_compare(PM_result1, PMresult2,…) | PMcompare(1, 2, …) |
| Plot residuals | PM_result$op$plot(resid = T,…) | plot(op, resid = T) |
| Construct VPC, pcVPC, NPDE | PM_result$valid() or PM_valid$new() | makeValid() |
| Plot VPC, pcVPC, NPDE | PM_valid$plot() | plot(PMvalid) |
| Stepwise covariate regression | PM_result$step() | PMstep() |
Other functions
| Function | R6 | Legacy |
|---|---|---|
| Calculate AUC | $auc() method for PM_result$op/$post/$pop, or PM_sim | makeAUC() |
| Simulate | PM_result$sim() or PM_sim$new() | SIMrun() |
| Probability of target attainment | PM_sim$pta() or PM_pta$new() | makePTA() |
Again, all functions have extensive help files and examples which can
be examined in R by using the help(command) or
?command syntax.