7 The results

7.1 PM_result details

After a successful NPAG/NPOD run, an R datafile is saved in the /outputs subdirectory of the newly created numerically ordered folder in the working directory. This file is called “PMout.Rdata”. These data files can be loaded by ensuring that the Runs folder is set as the working directory or using the path argument to $fit(), and then using the Pmetrics command PM_load.

There are several data objects contained within the Rdata files which are loaded, making these objects available for plotting and other analysis. This is in contrast to the Legacy method of loading objects into your global R environment, suffixed with the run number, e.g., “op.1” or “final.1”. Obscurely loading objects into memory is not good or current programming practice.

Therefore, in R6 Pmetrics, PM_load() returns a PM_resultobject. The fields in the object are in the table below.

Objects	Fields	Methods	Comments
$op (class: PM_op)	$id		Subject identification
	$time		Observation time in relative decimal hours
	$obs		Observation
	$cens		If any observation is censored (bloq, aloq) or none.
	$pred		Predicted value
	$pred.type		Type of prediction, i.e. based on the population parameter values or Bayesian posterior parameter values
	$icen		Median (default) or mean of the parameter distributions used to calculate the predicted values.
	$outeq		Output equation number
	$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
	$obsSD		Calculated standard deviation (error) of the observation based on the assay error polynomial
	$d		Difference between pred and obs
	$ds		Squared difference between pred and obs
	$wd		$d, weighted by the $obsSD
	$wds		$ds, weighted by the $obsSD
	$data		All of the above fields as a single data frame
		$plot	See `plot.PM_op` for details
		$summary	See `summary.PM_op` for details
		$auc	See `makeAUC` for details
$final (class: PM_final)	$popPoints		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
	$popMean		The final cycle mean for each random parameter distribution
	$popSD		The final cycle standard deviation for each random parameter distribution
	$popCV		The final cycle coefficient of variation for each random parameter distribution
	$popVar		The final cycle variance for each random parameter distribution
	$popCov		The final cycle covariance matrix for each random parameter distribution
	$popCor		The final cycle correlation matrix for each random parameter distribution
	$popMedian		The final cycle median for each random parameter distribution
	$postPoints		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
	$postMean		A data frame of means of posterior distributions for each subject and parameter
	$postSD		A data frame of SDs of posterior distributions for each subject and parameter
	$postVar		A data frame of variances of posterior distributions for each subject and parameter
	$postCov		An data frame of covariance matrices for posterior parameter values for each subject
	$postCor		An data frame of correlation matrices for posterior parameter values for each subject
	$shrikage		Data frame of average(postVar) / popVar for each parameter
	$gridpts		The initial number of support points
	$ab		Data frame 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
	$data		All of the above fields as a single list
		$plot	See `plot.PM_final` for details
		$summary	See `summary.PM_final` for details
$cycle (class: PM_cycle)	$names		Vector of names of the random parameters
	$objective		Data frame of cycle number, -2*Log-likelihood, AIC, and BIC at each cycle
	$gamlam		A data frame of cycle number and gamma or lambda value at each cycle for each output with type of error model
	$mean		A data frame of cycle number and the mean of each random parameter at each cycle, normalized to initial mean
	$sd		A data frame of cycle number and the standard deviation of each random parameter at each cycle, normalized to initial standard deviation
	$median		A data frame of cycle number and the median of each random parameter at each cycle, normalized to initial standard deviation
	$aic		A data frame of cycle number and Akaike Information Criterion at each cycle
	$bic		A data frame of cycle number and Bayesian (Schwartz) Information Criterion at each cycle
	$data		All of the above fields as a single list
		$plot	See `plot.PM_cycle` for details
		$summary	See `summary.PM_cycle` for details
$cov (class: PM_cov)	$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.
	$data		All of the above fields as a single list
		$plot	See `plot.PM_cov` for details
		$summary	See `summary.PM_cov` for details
$pop (class: PM_pop)	$id		Subject identification
$post (class: PM_post)	$time		Time of each prediction at a frequency specified in the NPrun() command, with a default of 12 minutes.
	$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
		$auc	See `makeAUC` for details
		$nca	See `makeNCA` for details
$data (class: PM_data)			Your original raw data object , see `PM_data` for details
$model (class: PM_model)			Your original model object, see `PM_model` for details
$errfile			Name of error file if it exists
$success			Boolean for successful run

To access the fields in a PM_result object, use the “$”.

# load the results of run1
run1 <- PM_load(1, path = "Runs")
run1$op # observed vs. predicted PM_op R6 object
run1$op$time # times in PM_op
run1$op$data # this accesses the whole observed vs. predicted raw data frame

Most of the fields are themselves R6 objects with methods. We’ll dive into this in more detail in the next chapter.

# summarize observed vs. predicted data
run1$op$summary()
# plot it
run1$op$plot()

The PM_result object itself also contains several methods in addition to the R6 objects in fields. The table below lists these methods (functions) and their descriptions.

Methods	Comments
$new	This method is not called directly, but new PM_result objects are created using `PM_load`
$plot	Alternative method to plot objects, making these equivalent
	`PM_result$plot("op")`
	`PM_result$op$plot()`
	`PM_result$op$data$plot()`
	`plot(PM_result$op)`
$summary	Alternative method to summarize objects, making these equivalent
	`PM_result$summary("final")`
	`PM_result$final$summary()`
	`PM_result$final$data$summary()`
	`summary(PM_result$final)`
$fit	Fit data using the model in the `PM_result` object
$auc	Calculate auc by supplying a src, e.g. `PM_result$auc("op")`
$report	Regenerate the report
$sim	Simulate using the model in the `PM_result` object
$save	Save the `PM_result` object
$validate	Validate by simuation to create VPC or NPDE as a `PM_valid` object
$step	Stepwise forward/backward linear regression between covariates and model parameter values
$opt	Optimal sampling to create a `PM_opt` object