PLOTR: Create Diagnostic Plots for a NONMEM Run
In metrumrg: Pharmacometric Tools for Data Preparation, Modeling, Simulation, and Reporting

Description Usage Arguments Details Value Author(s) References See Also

PLOTR is a function to generate diagnostic plots and/or covariate evaluation plots following a successful NONMEM run. It is called by NONR if diagnostic plots are requested or can be called independently following a NONMEM run. Plots use the pdf device. Specific control stream syntax is required: see Note under NONR .

PLOTR(
	run,
	...,
	project=getwd(), 
	rundir=filename(project,run),
	grp = NULL,
	onefile=TRUE,
	plotfile=plotfilename(run,project,grp,onefile),
	logtrans = FALSE, 
	dvname = 'DV', 
	epilog=NULL,
	grpnames = NULL, 
	cont.cov = NULL, 
	cat.cov = NULL, 
	par.list = NULL, 
	eta.list = NULL, 
	missing = -99,
	estimated = NULL,
	superset = FALSE
)

`run`	a control stream name, typically integer
`project`	the directory containing run subdirectories
`rundir`	path for the NONMEM run directory (‘project/*’); passed to `dataSynthesis`
`grp`	item in NONMEM data file or output table file (default) that can be used to condition plots generated by `PLOTR`. Default value is `NULL`. Example: `grp=c('SEX')`. Can be more than one, e.g,. `grp=c('SEX','TRT')`. When specifying `grp`, you can also specify `include.all=TRUE`, which will be understood by `diagnosticPlots` and cause the data to be plotted collectively as well as group-wise.
`onefile`	whether to produce one output file or many; passed to `pdf`
`plotfile`	file name for diagnostic plots, if any. Default combines ‘DiagnosticPlotReview’ with the run number, and `grp` if present. A counter is supplied if `onefile=FALSE`. You can specify an arbitrary name, coordinating with the value of `onefile`. Any asterisk will be replaced with the run name.
`logtrans`	Whether to transform the NONMEM output variables `DV, NPRED, CPRED, CPREDI, EPRED PRED, and IPRED`. Default: `FALSE`.
`dvname`	name of the dependent variable to use as a label for the diagnostic plots; default: `DV`
`epilog`	User-defined function or script to call at end of `NONR` or `PLOTR`. A non-null argument that cannot be coerced by `match.fun` to a function will be treated as a filename to be sourced. All the arguments normally available to `PLOTR (run, project, dvname, logtrans, grp, grpnames, cont.cov, at.cov, par.list, eta.list, missing, etc)` will be available to `epilog`, as well as any extra arguments you pass to `NONR` or `PLOTR`. A function can declare any of these, but should at minimum contain the ... argument. A script can expect them to be present. See also ‘inst/example/epilog.R’ in this package. To see exactly what is available, try `epilog=function(...)cat(names(list(...)))`.
`grpnames`	optional vector of names for `grp` item. Vector length must equal number of conditions in `grp` and must have an order corresponding to an increasing sort of `grp`. Default value is `NULL`. Example: `grpnames=c('Male','Female')`
`cont.cov`	vector of continuous covariate names. Names must match those used as column headers in the data file (identified in the control stream). Values are retrieved from the data file if not part of the NONMEM $TABLE step. Default value is `NULL`. Example: `cont.cov=c('AGE','WT','CLCR')`
`cat.cov`	vector of categorical covariate names. Names must match those used as column headers in `DataFile`. Values are retrieved from the data file if not part of the NONMEM $TABLE step. Default value is `NULL`. Example: `cat.cov=c('SEX','FOOD')`
`par.list`	vector of NONMEM model parameter names. Values are retrieved from ‘par.TAB’ created in NONMEM if not in ‘.TAB’. Default value is `NULL`. This can be a superset of parameters but only those present in NONMEM output table will be used. Example: `par.list=c('CL','V','V2','Q')`
`eta.list`	vector of NONMEM model random effect names. Values are retrieved from ‘par.TAB’ created in NONMEM if not in ‘.TAB’. Default value is `NULL`. This can be a superset of random parameters but only those present in NONMEM output table will be used. Example: `eta.list=c('ETA1','ETA2','ETA3','ETA4')`
`missing`	numeric item that defines value used to represent missing items in the NONMEM data file. Default value is '-99'.
`estimated`	character vector of names for items that NONMEM estimates. Used to annotate parameter and gradient search plots.
`superset`	(experimental) whether to use `superset` as an intermediate for dataset creation (instead of `dataSynthesis`). Could give time-varying covariates, whereas the default gives only static covariates.
`...`	additional arguments passed to functions that accept them. For example, you can pass `onefile=FALSE` to `pdf`. You can also pass additional lattice arguments to modify the diagnostic plots.

PLOTR creates a plotting dataset using dataSynthesis. It passes this dataset to each of diagnosticPlots, covariatePlots, and cwresPlots. It then calls the function named by the epilog argument, if any. The example epilog (‘example/epilog.R’) calls dataSynthesis itself, and does additional plotting.

The ... argument can be used creatively, with appropriate caution. Extra arguments are generally passed to secondary functions that accept them, and even some that don't. All the lattice plotting functions accept extra arguments, so you may be able to modify the diagnostic plots judiciously (with the caviat that the same arguments will be passed to diagnosticPlots, covariatePlots, and cwresPlots. pdf technically does not accept extra arguments, but any specified argument that it does accept will be passed.

File names deserve special consideration. plotfile gives the name (or naming strategy) for the diagnostic plots; it is passed to pdf and has a suitable default. If an alternative is specified, ‘*’ will be replaced with run, the run name. For example, the default ‘pdf’ name is ‘project/DiagnosticPlotReview_*.pdf’, but you could change it to ‘project/*/DiagnosticPlotReview.pdf’.

data.frame (the plotting data set), returned invisibly

Tim Bergsma

http://metrumrg.googlecode.com