Objects created after a run

After a successful IT2B or NPAG run, an R datafile is saved in the output subdirectory of the newly created numerically ordered folder in the working directory. After IT2B, this file is called “IT2Bout.Rdata”, and after NPAG it is called “NPAGout.Rdata”. These data files can be loaded by ensuring that the Runs folder is set as the working directory, and then using the Pmetrics commands PM_load() in R6 or PMload() for Legacy.

There are several Pmetrics data objects contained within the Rdata files which are loaded, making these objects available for plotting and other analysis.

R6

PM_load() returns a PM_result object. The fields in the object are in the table below.

cov (class: PM_cov, R6) $clone Method: Create copy of PM_cov object$data Data frame, class: PMcov, same as Legacy
id: Subject identification
time: Time for each covariate entry
covariates…Covariate values for each subject at each time, extracted from the raw data file
parameters…Mean, median, or mode of Bayesian posterior distribution for each random parameter in the model. Mode summaries are available for NPAG output only, and the default is median. Values are recycled for each row within a given subject, with the number of rows driven by the number of covariate entries
icen: Median (default) or mean of the covariates and parameter value distributions.
$initialize Method: Called by PM_cov$$new(), creates new PM_cov object, happens automatically at end of run, generally not a user function | | |\plot |Method: Plot the PM_cov object with plot.PMcov() | | |\print |Method: display the PM_cov object as a data frame | | |\summary |Method: summarize the PM_cov object with summary.PMcov(), same function as for Legacy | |cycle (class: PM_cycle, R6) |\aic |A matrix of cycle number and Akaike Information Criterion at each cycle | | |\bic |A matrix of cycle number and Bayesian (Schwartz) Information Criterion at each cycle | | |\clone |Method: Create copy of PM_cycle object | | |\gamlam |A matrix of cycle number and gamma or lambda at each cycle (see item #16 under NPAG Runs below for a discussion of gamma and lambda) | | |\initialize |Method: Called by PM_cycle$$new(), creates new PM_cycle object, happens automatically at end of run, generally not a user function$ll Matrix of cycle number and -2*Log-likelihood at each cycle
$mean A matrix of cycle number and the mean of each random parameter at each cycle, normalized to initial mean$median A matrix of cycle number and the median of each random parameter at each cycle, normalized to initial standard deviation
$names Vector of names of the random parameters$plot Method: Plot the PM_cycle object with plot.PMcycle()
$sd A matrix of cycle number and the standard deviation of each random parameter at each cycle, normalized to initial standard deviation data (class: PM_data, R6) See Pmetrics Input Files. Your original raw data file. final (class: PM_final, R6)$ab Matrix of boundaries for random parameter values. For NPAG, this is specified by the user prior to the run; for IT2B, it is calculated as a user specified multiple of the SD for the parameter value distribution
$clone Method: Create copy of PM_final object$data Data frame with all data fields, class: PMfinal, same as Legacy
$gridpts (NPAG only) The initial number of support points$initialize Method: Called by PM_fiinal$$new(), creates new PM_final object, happens automatically at end of run, generally not a user function | | |\nsub |Number of subjects | | |\plot |Method: Plot the PM_final object with plot.PM_final() | | |\popCor |The final cycle correlation matrix for each random parameter distribution | | |\popCov |The final cycle covariance matrix for each random parameter distribution | | |\popCV |The final cycle coefficient of variation for each random parameter distribution | | |\popMean |The final cycle mean for each random parameter distribution | | |\popMedian |The final cycle median for each random parameter distribution | | |\popPoints |(NPAG only) Data frame of the final cycle joint population density of grid points with column names equal to the name of each random parameter plus \prob for the associated probability of that point | | |\popRanFix |The final cycle values for all fixed but random parameters | | |\popSD |The final cycle standard deviation for each random parameter distribution | | |\popVar |The final cycle variance for each random parameter distribution | | |\postCor |An array of correlation matrices for posterior parameter values for each subject | | |\postCov |An array of covariance matrices for posterior parameter values for each subject | | |\postMean |A matrix of means of posterior distributions for each subject and parameter | | |\postPoints |(NPAG only) Data frame of the Bayesian posterior parameter points for each of the first 100 subjects, with the following columns: | | | |id: subject ID | | | |point: point number for that subject | | | |parameters: parameters in the model | | | |prob: probability of each point in the posterior for each patient | | |\postSD |A matrix of SDs of posterior distributions for each subject and parameter | | |\postVar |A matrix of variances of posterior distributions for each subject and parameter | | |\shrinkage |Shrinkage values for each random population parameter | | |\summary |Method: summarize the PM_final object with summary.PMfinal(), same function as for Legacy | |ITdata (class: IT2B, list) | |Raw data used to make the above objects. Please use ?ITparse in R for discussion of the data contained in these objects | |NPdata (class: NPAG, list) | |Raw data used to make the above objects. Please use ?NPparse in R for discussion of the data contained in these objects | |op (class: PM_op, R6) |\auc |Method: makeAUC() to calculate area under time concentration curve | | |\block |Dosing block, usually 1 unless data file contains EVID=4 dose reset events, in which case each such reset within a given ID will increment the dosing block by 1 for that ID | | |\clone |Method: Create copy of PM_op object | | |\d |Difference between pred and obs | | |\data |Data frame with all data fields, class: PMop, same as Legacy | | |\ds |Squared difference between pred and obs | | |\icen |Median (default) or mean of the parameter distributions used to calculate the predicted values. | | |\id |Subject identification | | |\initialize |Method: Called by PM_op$$new(), creates new PM_op object, happens automatically at end of run, generally not a user function
$obs Observation$obsSD Calculated standard deviation (error) of the observation based on the assay error polynomial
$outeq$plot Method: Plot the PM_op object with plot.PM_op()
$pred Predicted value$pred.type Type of prediction, i.e. based on the population parameter values or Bayesian posterior parameter values
$summary Method: summarize the PM_op object with summary.PMop(), same function as for Legacy$time Observation time in relative decimal hours
$wd$d, weighted by the $obsSD$wds $ds, weighted by the$obsSD
pop (class: PM_pop, R6) $auc Method: makeAUC() to calculate area under time concentration curve post (class: PM_post, R6)$block Same as for PMop objects above
NPAG only $clone Method: Create copy of PM_pop or PM_post object$data Data frame with all data fields, class: PMpop or PMpost, same as Legacy
$icen Median (default) or mean of the parameter distributions used to calculate the predicted values.$id Subject identification
$initialize Method: Called by PM_pop$$new() or PM_post$$new(), creates new PM_pop or PM_post object, happens automatically at end of run, generally not a user function$outeq Output equation for each prediction
$pred Population prior (PMpop) or Bayesian posterior (PMpost) predictions for each output equation$time Time of each prediction at a frequency specified in the NPrun() command, with a default of 12 minutes.
valid (class: PM_valid, R6) Use the command str(valid.x) in R, where x is the run number This is a list containing the information to perform graphical and numerical analysis of prediction checks and normalized prediction distribution errors. It is a method of internal model validation.
This object will only be present if you have run $validate(…) after a run is completed. valid$simdata (class: PMsim, list) $obs A data frame with$id, $time,$out, $outeq columns containing simulated observations at each time and output equation number in the template data file. If simulations from multiple template subjects have been combined (see Simulator Runs), then$id will be of the form x.y, where x is the simulation number, and y is the template number.
$amt A data frame with$id, $time,$out, $comp columns containing simulated amounts in each compartment.$parValues A data frame with $id, … columns containing the parameter value sets for each simulated subject with “…” signifying the columns named according to the names of the random parameters in the model$totalSets The total number of simulated sets of parameters, which may be greater than the requested number if limits were specified in the simulation (see Simulator Runs).
$totalMeans The means of the parameter values in the total simulated sets which can be used as a check of the adequacy of the simulation to reproduce the requested mean values when limits were applied. The final truncated set will likely not have the requested mean values.$totalCov The covariances of the parameter values in the total simulated sets which can be used as a check of the adequacy of the simulation to reproduce the requested covariance values when limits were applied. The final truncated set will likely not have the requested covariance values.
valid$timeBinMedian (class: data frame)$bin Time bin number
$time Median time for each bin valid$tadBinMedian (class: data frame) $bin Time after dose bin number$time Median time after dose for each bin
valid$opDF (class: data frame)$id, $time,$obs, $pred,$icen, $outeq,$block, $obsSD,$ds, $wd,$wds See op above.
$tad Time after dose$PRED_bin Median prediction for each bin
$pcObs Prediction corrected observation (based on bin)$timeBinNum Number of each time bin
$timeBinMedian Median time for each bin$tadBinNum Number of each time after dose bin
$tadBinMedian Median time after dose for each bin valid$npde (class: NpdeObject) A list of object suitable for plotting an npde.

To access the fields in a PM_result object, use the “$”. res1 <- PM_load(1) res1$op
res1$op$time
res1$op$data #this accesses the whole observed vs. predicted data frame

Most of the fields are themselves R6 objects with methods.

res1 <- PM_load(1)
res1$op res1$op$summary() res1$op$plot() Legacy PMload() returns a number of objects into the R environment, suffixed by the run number supplied as an argument to PMload(). Objects Variables Comments op (class: PMop, list)$block Dosing block, usually 1 unless data file contains EVID=4 dose reset events, in which case each such reset within a given ID will increment the dosing block by 1 for that ID
$d Difference between pred and obs$ds Squared difference between pred and obs
$icen Median (default) or mean of the parameter distributions used to calculate the predicted values.$id Subject identification
$obs Observation$obsSD Calculated standard deviation (error) of the observation based on the assay error polynomial
$outeq$pred Predicted value
$pred.type Type of prediction, i.e. based on the population parameter values or Bayesian posterior parameter values$time Observation time in relative decimal hours
$wd$d, weighted by the $obsSD$wds $ds, weighted by the$obsSD
final (class: PMfinal, list) $ab Matrix of boundaries for random parameter values. For NPAG, this is specified by the user prior to the run; for IT2B, it is calculated as a user specified multiple of the SD for the parameter value distribution$gridpts (NPAG only) The initial number of support points
$popCor The final cycle correlation matrix for each random parameter distribution$popCov The final cycle covariance matrix for each random parameter distribution
$popCV The final cycle coefficient of variation for each random parameter distribution$popMean The final cycle mean for each random parameter distribution
$popMedian The final cycle median for each random parameter distribution$popPoints (NPAG only) Data.frame of the final cycle joint population density of grid points with column names equal to the name of each random parameter plus $prob for the associated probability of that point$popRanFix The final cycle values for all fixed but random parameters
$popSD The final cycle standard deviation for each random parameter distribution$popVar The final cycle variance for each random parameter distribution
$postCor An array of correlation matrices for posterior parameter values for each subject$postCov An array of covariance matrices for posterior parameter values for each subject
$postMean A matrix of means of posterior distributions for each subject and parameter$postPoints (NPAG only) Data frame of the Bayesian posterior parameter points for each of the first 100 subjects, with the following columns:
id: subject ID
point: point number for that subject
parameters: parameters in the model
prob: probability of each point in the posterior for each patient
$postSD A matrix of SDs of posterior distributions for each subject and parameter$postVar A matrix of variances of posterior distributions for each subject and parameter
$shrinkage Shrinkage values for each random population parameter cycle (class: PMcycle, list)$aic A matrix of cycle number and Akaike Information Criterion at each cycle
$bic A matrix of cycle number and Bayesian (Schwartz) Information Criterion at each cycle$gamlam A matrix of cycle number and gamma or lambda at each cycle (see item #16 under NPAG Runs below for a discussion of gamma and lambda)
$ll Matrix of cycle number and -2*Log-likelihood at each cycle$mean A matrix of cycle number and the mean of each random parameter at each cycle, normalized to initial mean
$median A matrix of cycle number and the median of each random parameter at each cycle, normalized to initial standard deviation$names Vector of names of the random parameters
$sd A matrix of cycle number and the standard deviation of each random parameter at each cycle, normalized to initial standard deviation cov (class: PMcov, data.frame)$icen Median (default) or mean of the covariates and parameter value distributions.
$id Subject identification$time Time for each covariate entry
covariates… Covariate values for each subject at each time, extracted from the raw data file
parameters… Mean, median, or mode of Bayesian posterior distribution for each random parameter in the model. Mode summaries are available for NPAG output only, and the default is median. Values are recycled for each row within a given subject, with the number of rows driven by the number of covariate entries
pop (class: PMpop, data.frame) $id Subject identification post (class: PMpost, data.frame)$time Time of each prediction at a frequency specified in the NPrun() command, with a default of 12 minutes.
NPAG only $icen Median (default) or mean of the parameter distributions used to calculate the predicted values.$pred Population prior (PMpop) or Bayesian posterior (PMpost) predictions for each output equation
$outeq Output equation for each prediction$block Same as for PMop objects above
NPdata (class: NPAG, list) ITdata (class: IT2B, list Raw data used to make the above objects. Please use ?NPparse or ?ITparse in R for discussion of the data contained in these objects
mdata (class: PMmatrix, data.frame) See Pmetrics Input Files. Your original raw data file.
valid (class: PMvalid, list) Use the command str(valid.x) in R, where x is the run number This is a list containing the information to perform graphical and numerical analysis of prediction checks and normalized prediction distribution errors. It is a method of internal model validation.
This object will only be present if you have run $validate(…) after a run is completed. valid$simdata (class: PMsim, list) $obs A data frame with$id, $time,$out, $outeq columns containing simulated observations at each time and output equation number in the template data file. If simulations from multiple template subjects have been combined (see Simulator Runs), then$id will be of the form x.y, where x is the simulation number, and y is the template number.
$amt A data frame with$id, $time,$out, $comp columns containing simulated amounts in each compartment.$parValues A data frame with $id, … columns containing the parameter value sets for each simulated subject with “…” signifying the columns named according to the names of the random parameters in the model$totalSets The total number of simulated sets of parameters, which may be greater than the requested number if limits were specified in the simulation (see Simulator Runs).
$totalMeans The means of the parameter values in the total simulated sets which can be used as a check of the adequacy of the simulation to reproduce the requested mean values when limits were applied. The final truncated set will likely not have the requested mean values.$totalCov The covariances of the parameter values in the total simulated sets which can be used as a check of the adequacy of the simulation to reproduce the requested covariance values when limits were applied. The final truncated set will likely not have the requested covariance values.
valid$timeBinMedian (class: data frame)$bin Time bin number
$time Median time for each bin valid$tadBinMedian (class: data frame) $bin Time after dose bin number$time Median time after dose for each bin
valid$opDF (class: data frame)$id, $time,$obs, $pred,$icen, $outeq,$block, $obsSD,$ds, $wd,$wds See op above.
$tad Time after dose$PRED_bin Median prediction for each bin
$pcObs Prediction corrected observation (based on bin)$timeBinNum Number of each time bin
$timeBinMedian Median time for each bin$tadBinNum Number of each time after dose bin
$tadBinMedian Median time after dose for each bin valid$npde (class: NpdeObject) A list of object suitable for plotting an npde.

The objects are the same as the fields in a PM_result object, except for the valid field, which is not a loaded object. The disadvantage of this approach compared to R6 is that there is no indication what is loaded into R with this command. If you had previously added to your run results with PMsave(), you would not necessarily know that there were additional results when you executed PMload().

PMload(1)
op.1
final.1
cycle.1
cov.1
post.1 #NPAG only
pop.1 #NPAG only
#other results could be included if PMsave() had been run previously

Because Legacy Pmetrics works fully under the S3 framework, these objects are passed to functions and do not have methods attached to them.