superset: Augment NONMEM Input with Table Output
In metrumrg: Pharmacometric Tools for Data Preparation, Modeling, Simulation, and Reporting

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

Given the name of a NONMEM run, create a superset of data that has all of the run input data and any data recoverable from the output of table records.

superset(
	run, 
	project = getwd(), 
	rundir = filename(project, run), 
	ctlfile = filename(rundir, run, ".ctl"), 
	key = character(0), 
	read.input = list(
		read.csv, 
		header = TRUE, 
		as.is = TRUE
	), 
	read.output = list(
		read.table, 
		header = TRUE, 
		as.is = TRUE, 
		skip = 1, 
		comment.char = "", 
		check.names = FALSE
	), 
	exclusive=NULL,
	digits=5,
	...
)
ignored(
	run, 
	project = getwd(), 
	rundir = filename(project, run), 
	ctlfile = filename(rundir, run, ".ctl"), 
	read.input=list(read.csv,header=TRUE,as.is=TRUE),
	...
)

`run`	a run name, as for `NONR`
`project`	parent of the run directory
`rundir`	path to the run directory
`ctlfile`	name of the control stream
`key`	the object model for the input data
`read.input`	a methodology for acquiring the input
`read.output`	a methodology for acquiring the output
`exclusive`	character vector of output column names to exclude; or logical: whether to keep columns with re-used names
`digits`	significant digits for assessing informativeness when `exclusive=NULL`
`...`	ignored

Given a run name and project directory, superset figures out the run directory and location of a NONMEM control stream. It reads the control stream to identify the run-time location of input and output files, as well as the "ignore" (and/or "accept") criteria that relate extent of input records to extent of output records. read.input and read.output are lists consisting of functions and arguments appropriate for reading input and output file formats, respectively. The ignore criteria will be reconstructed per row so that output can be mapped unambiguously to input. A column with run as its name is bound to the input data, showing 1 where a record was visible to NONMEM, and 0 otherwise.

Normally, superset tries to bind output columns directly to input. Alternatively, if key is provided, it is used as an object model to allow an inferential left join of output onto input; this approach is riskier, but can back fill NA cells with values that are otherwise constant within left-subsets of the key.

During integration, naming convention of the input is retained, and output column names are mapped by position, using the control stream input criteria. Output tables are restored to input dimensions using the "ignore" criteria, then checked for length: currently, superset ignores output tables having fewer rows than the input, as well as output tables whose row count is not a multiple of input row count.

Output tables may contain versions of input columns. Disposition depends on the value of exclusive. If a character vector, it lists columns to exclude from output. If TRUE, all columns with re-used names will be dropped. If FALSE, such columns will be renamed (*.n, where n is table number). If NULL, only informative columns will be retained and renamed. A column is informative if any element is informative. An element is informative if it is newly generated (not NA and not zero, but original is NA) or if it is an alteration (non-NA, and different from non-NA original). If the column pair can be interpreted as numeric, "different" is determined using only the first digits digits.

Only the first instance of any column among successive output tables is retained.

ignored takes a subset of superset arguments and returns just a logical vector showing which input rows are dropped. Note that it is possible to invoke either function using just run, just rundir, or just ctlfile, supplying project as necessary. Normally these three are tightly coordinated and may be inferred from each other.

superset: data.frame where row count is a multiple of (usually equal to) input row count
ignored a logical vector indicating which rows were dropped.

In the control stream, avoid use of FIRSTONLY, as this alters the number of rows. Tables created using FIRSTONLY can be summarized by superset if key is provided. Note that when key is provided, innocuous warnings result (e.g. 'nothing to merge') if items are tabled that are already present in the original data set.

Early versions of these functions supported the documented ignore/accept syntax, e.g. REP.GT.0. As of v. 5.52, Fortran 95 syntax is also supported, e.g. REP > 0.

Tim Bergsma

http://metrumrg.googlecode.com