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.
| Objects | Fields | Comments |
|---|---|---|
| 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() | |
| 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 frameMost 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 previouslyBecause Legacy Pmetrics works fully under the S3 framework, these objects are passed to functions and do not have methods attached to them.