NONR: Run NONMEM
In metrumrg: Pharmacometric Tools for Data Preparation, Modeling, Simulation, and Reporting

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

NONR executes, from R, a NONMEM run for which there exists a compatible (see note) control stream. Supported platforms include MS Windows and Unix-like operating systems (Nix). Special support is included for Sun Grid Engine with Nix. Defaults are currently chosen for NONMEM 7.3. Generally, NONMEM needs to be installed using NMQual (http://nmqual.googlecode.com). See also autolog.pl. Execution on the Nix grid requires the installation of Sun Grid Engine v6. Following a successful NONMEM run NONR can call PLOTR to create diagnostic plots (pdf format) and/or run a user-written script.

NONR(
	run, 
	...,
	command, 
	project = getwd(), 
	wait = TRUE,
	grid = FALSE, 
	concurrent = grid & wait,
	udef= FALSE, 
	invisible=udef,
	compile = TRUE,
	execute = TRUE,
	split = FALSE,
	checkrunno = TRUE, 
	checksum = TRUE, 
	diag = wait, 
	fdata = TRUE, 
	logtrans = FALSE,
	nice= TRUE, 
	epilog = NULL, 
	dvname = NULL, 
	grp = NULL, 
	grpnames = NULL, 
	cont.cov = NULL, 
	cat.cov = NULL, 
	par.list = NULL, 
	eta.list = NULL, 
	missing = -99,
	interface='autolog.pl',
	q=NA,
	pe=NA
)

`run`	vector of control stream names. Typically integer. e.g. 1:10 corresponds to 1.ctl, 2.ctl, ... 10.ctl. Character names are supported, especially '001' etc. But beware! Names with non-digit characters may match patterns in `purgeRunDir` and are therefore strongly discouraged.
`command`	path for a script to run NONMEM, e.g., `command='C:/nm6/test/nm6.pl'`. The script is assumed to be an NMQual-generated wrapper for NONMEM execution, but may also be arbitrarily defined by the user (`udef=TRUE`). In the former case, appropriate arguments and modifiers are added to build a typical NMQual commandline (`nm.pl` or `autolog.pl`), conditionally wrapped in the arguments for a typical grid commandline (`qsub`). The path may be given relative to the current directory. `command` may be a character vector of length greater than one: each element will be run in succession. If `command` is missing, an attempt will be made to locate a NONMEM installation using `findNonmemCommand` (as of package version 5.15). DISCLAIMER: it is the responsibility of the user to ensure that the command thus-identified is appropriate.
`project`	directory in which run-specific subdirectories will be created. Typically also contains original control streams. Use an absolute path (safer) or specify relative to the current working directory.
`wait`	If `wait` is `FALSE` (e.g. for large batches of simulations or bootstraps) and `grid` is `TRUE`, the job will run asynchronously and no cleanup or plotting will be attempted. Default `TRUE`, gives synchronous runs on the grid, but these are usually limited in number. New in version 5.22 (replaces `boot`). `wait` also controls the defaults for `diag` and `sync`): see runNonmem.
`grid`	whether NONMEM execution should be wrapped in a call to Sun Grid Engine's `qsub` utility. `FALSE` by default. Set to `TRUE` explicitly for regular runs using a grid. Coerced to `FALSE` for Windows.

concurrent

Should the runs represented by elements of run be run concurrently as separate processes? Normally TRUE if grid is TRUE, since this is the primary advantage of using a grid. Coerced to FALSE on Windows. Concurrency is implemented using the package fork.

As of version 5.22, this argument defaults to TRUE only for regular runs on the grid. Unsynchronized (wait is FALSE) runs on the grid return control to the console almost immediately (sync='n') so there is little advantage for each run to have its own process.

`udef`	a logical indicating whether `command` is user defined. If so, the `command` is simply wrapped in a system call rather than pre-converted to a (possibly grid-ready) NMQual commandline. Default: `FALSE`
`invisible`	`intern`, `minimized`, and `invisible` can be specified for the system call that runs NONMEM. metrumrg will largely ignore these on a unix-like platform. For Windows, `invisible` is `TRUE` by default when `udef` is `TRUE`, and `FALSE` otherwise. If `FALSE`, NONMEM output will be displayed in a command window during the run. Set `invisible=TRUE` to suppress this display. See the Windows help for `system`. To explore interactively, use `debug(runCommand)`.
`compile`	whether to compile NONMEM (i.e., make nonmem.exe). Set to `FALSE` if you already did this in a previous step and merely want to execute.
`execute`	whether to execute the compiled NONMEM (i.e., invoke nonmem.exe). Set to `FALSE` if you merely want to compile, e.g. to verify compile success without committing to a run. You can run the compiled object later with `compile=FALSE`.
`split`	whether to compile and execute as separate steps. If both compile and execute are `TRUE`, the run can be split into two separate steps. Though `split`, `compile`, and `execute` can be manipulated independently, it makes no sense to split a run unless `compile` and `execute` are both `TRUE`. The greatest advantage to splitting is realized on a grid, with `grid=TRUE`: runs will be split and compile steps will by default be run in their own queue, for efficiency.
`checkrunno`	whether to check/correct the control stream to ensure that standard uses of the NONMEM control stream name match the name listed in `run` vector. Default: `TRUE`. For files, e.g. `../3.TAB`, path separator must be that recognized by `dirname` and `basename`. Only one usage per line of text will be fixed. ‘Standard’ uses currently include: the first word after $PROB(LEM) (not counting RUN or RUN\#); ‘.tab’ (case insensitive); ‘par.tab’ (case insensitive); ‘*.msf’ (case insensitive) except on a line that starts with $MSFI.
`checksum`	If `TRUE` (default), checksums are requested from `nm.pl` when wrapping NONMEM execution. `FALSE` is useful for development.
`diag`	whether to plot standard diagnostic plots. Default: `TRUE` for synchronized runs. You can override the default file name by passing `plotfile`. See `PLOTR` for details. Also see Note below for required control stream syntax, e.g. expected tables.
`fdata`	whether to attempt deletion of NONMEM files FDATA and PRDERR. Default: `TRUE`.
`logtrans`	passed to PLOTR
`nice`	whether the NONMEM run directory, based on `run`, is deleted or simply emptied prior to the execution of NONMEM. If `nice=TRUE` (default), hidden files (as defined for `all.files` in the function `dir`) are not deleted, e.g., any `.svn` directory.
`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(...)))`.
`dvname`	name of the dependent variable to use as a label for the diagnostic plots. Default: DV.
`grp`	passed to `PLOTR`
`grpnames`	passed to `PLOTR`
`cont.cov`	passed to `PLOTR`
`cat.cov`	passed to `PLOTR`
`par.list`	passed to `PLOTR`
`eta.list`	passed to `PLOTR`
`missing`	passed to `PLOTR`
`interface`	the name of a function to prepare NONMEM command lines
`q`	choice of queue, passed to `qsub`
`pe`	choice of parallelization environment, passed to `qsub`; implementation-specific: see your system administrator
`...`	additional arguments passed to functions that accept them. For example, you can pass `onefile=FALSE` to `pdf`, called by `PLOTR`. You can also pass additional lattice arguments to modify the diagnostic plots. You can gain finer control of run behavior by modifying arguments to `runNonmem`, e.g. `purge=FALSE`. Flags recognized by Sun Grid Engine's `qsub` are accepted by a like-named wrapper (this effect replaces the older SGEflgs argument). Example: to set a maximum run length of one hour and get an email if the run goes over one hour and is killed, include `l='h_rt=1:0:0', m='e',M='name@email.address'`. Passing N, o, e, V, j, q, sync, shell, b, or cwd will override defaults. You can pass multiple instances of an argument if `qsub` allows it. passing L will override a constitutive instance of l in `runCommand`. Values are character vectors. Lengths greater than one result in element-wise paste operations: a vector of corresponding length will be returned.

NONR is currently implemented as a wrapper that calls runNonmem for each element in run. It creates a like-named subdirectory for each run in project. It looks for <run>.ctl in project, cleans it up as necessary, and writes it to the subdirectory, in which context NONMEM is invoked (using runCommand). The output of NONMEM will be ‘<run>.lst’ in the subdirectory. Files matching patterns in purgeRunDir:standard will be removed (unless you pass purge=FALSE as a dots argument: see entry above for ...). Attempts will be made to run PLOTR and epilog. Then a ‘complete’ message is printed.

As of version 5.22, parallelization is directly supported. <run>.pnm is copied to the subdirectory, if present in the same directory as <run>.ctl. If not, template.pnm is copied to the subdirectory (if present in the same directory as <run>.ctl) and is renamed <run>.ctl. Use an NMQual-mediated NONMEM installation that expects this convention.

File names and locations can be manipulated somewhat, i.e., by over-riding runNonmem's defaults for rundir, outfile, streams, ctlfile, and remove.

an invisible list of the results of calls to runNonmem

Specific control stream syntax is expected when running NONR and the other functions present in the metrumrg package. The list of syntax requirements are as follows.

$PROB should be followed by ‘RUN\#’ then a number representing the control stream number. No commas should be used in the $PROB statement. ‘PROBLEM’ is an alternative for ‘PROB’. The run number is the first space-delimited alphanumeric sequence after PROB(LEM), ignoring RUN(\#). No ampersands are allowed in the problem statement.
The datafile name and relative path needs to be on the first line of the $DATA record immediately following ‘$DATA’.
A relative datafile path must be specified relative to runNonmem:rundir, typically a subdirectory of project. For example, ‘3.ctl’ will actually run as ‘path/project/3/3.ctl’; if its datafile is ‘path/data/DATA3’, then 3.ctl should specify “$DATA ../../data/DATA3”.
The NONMEM datafile must contain a ‘C’ column containing only C's or periods(‘.’). Typically this is the first column.
The ‘*.TAB’ file in the “$TABLE” step must contain an EVID column for plotting purposes. In the case of “$PRED” models, this can be a dummy column in the data file.
The NONMEM data file must contain a column with a header of ‘ID’ for plotting purposes.
File paths for ‘MSF’ files and ‘TAB’ files, etc., are generally expected to be relative paths, using ‘/’ as the directory separator. File paths with no separator are assumed to be relative to the directory in which the control stream is run: ‘./’ may be prepended. E.g. “$TABLE EVID FILE=100.tab” is taken as “$TABLE EVID FILE=./100.tab”.
$TABLE statments should include the ONEHEADER option, or problems may result.
Avoid the use of ampersands and greater-than, less-than symbols in comments: they confuse xml processors.

PLOTR will automatically generate CWRES plots if required files are present in NONMEM run directory. See help for compute.cwres for instructions on generating the files required for CWRES plots. PLOTR expects etas and model parameters to be output in the ‘*par.TAB’ file and variables for diagnostic plots to be output in the ‘*.TAB’ file, where ‘*’ represents the control stream number. Additional $TABLE records can be present in the control stream but these are not used/needed by PLOTR. Mechanisms and expectations are somewhat different for NONMEM7.

written by Bill Knebel; modified by Tim Bergsma.

http://metrumrg.googlecode.com

runNonmem
PLOTR

## Not run: 
#vignette:	
metrumrgURL('example/project/script/model.pdf')

#Assuming an NMQual-mediated NONMEM wrapper: /opt/NONMEM/nm72/nmqual/autolog.pl
#Assuming this is some script directory, and contol streams (e.g. 1.ctl) are in 
# a sibling directory "nonmem"

#regular run, no grid
path <- '/opt/NONMEM/nm72/nmqual/autolog.pl'
NONR(
	run=1,
	command=path,
	project='../nonmem',
	wait=TRUE,                 #default
	grid=FALSE,                #default
	diag=TRUE                  #default
)

#regular run on grid
NONR(
	run=1,
	command=path,
	project='../nonmem',
	wait=TRUE,                 #default
	grid=TRUE,
	diag=TRUE                  #default
)

#bootstrap run, no grid (uncommon)
NONR(
	run=1,
	command=path,
	project='../nonmem',
	wait=FALSE,                 
	grid=FALSE,                #default
	diag=FALSE                 #default
)

#bootstrap run on grid
NONR(
	run=1,
	command=path,
	project='../nonmem',
	wait=FALSE,
	grid=TRUE,
	diag=FALSE                 #default
)

## End(Not run)