Skip to contents

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


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.


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


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)

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.


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.


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.


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.


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.


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


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.


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().

sim.2 <- SIMparse("simout1.txt")

In the above example, sim.2 will be added to the .Rdata file for future retrieval with PMload(2).

Loading functions


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)

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")


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.