NONR {MIfuns} | R Documentation |
NONR executes a NONMEM run from R on MS Windows or the Nix grid. NONMEM needs to be installed on either OS using NMQual (http://nmqual.googlecode.com). 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.
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 are output as one pdf.
NONR(NMcom, b, ProjectDir, boot = 0, concurrent = TRUE, SGEflgs = "", checkrunno = TRUE, diag = TRUE, fdata = FALSE, epilog = NULL, dvname = NULL, logtrans = FALSE, covplt = FALSE, grp = NULL, grpnames = NULL, cont.cov = NULL, cat.cov = NULL, par.list = NULL, eta.list = NULL, missing = -99, dosbox = TRUE, nochecksum=FALSE, grid=FALSE, nice=F) PLOTR(b, ProjectDir, dvname = NULL, logtrans = FALSE, covplt = FALSE, grp = NULL, grpnames = NULL, cont.cov = NULL, cat.cov = NULL, par.list = NULL, eta.list = NULL, missing = -99)
NMcom |
The complete name of the perl script created by
NMQual when running on the cluster or the complete path plus perl
script name when running on Windows. On Windows with NONMEM 6
installed using NMQual 6 in C:/nm6, the command would be
NMcom="C:/nm6/test/nm6.pl" |
b |
Vector of (NONR) or single
(PLOTR) control stream number(s) to run in NONMEM. Should be numeric
with no placeholder zeros to left of number, i.e., "1" not
"001". Example: b=c(1,2,5) |
ProjectDir |
Full system path to the directory containing the NONMEM control (*.ctl) streams. |
boot |
Flag to describe type of NONMEM run with (0)-normal, (1)-bootstrap, (2)-long runs, and (3)-bootstrap runs across entire cluster. |
concurrent |
Tell NONR to whether to run control streams concurrently in NONMEM (default: TRUE). Coerced to FALSE in Windows. |
SGEflgs |
Flags to pass to Sun Grid Engine when
running on the Nix grid. Example: To set a run length of maximum one
hour and get an email sent if it goes over one hour and is killed.
SGEflags="-l h_rt=1:0:0 -m e -M name@email.address" |
checkrunno |
Whether to check/correct the control stream to
ensure that all uses of the NONMEM control stream number match the
number listed in b vector. Default: TRUE. |
diag |
Whether to plot standard diagnostic plots. Default: TRUE. |
fdata |
Whether to request deletion of NONMEM files: FDATA, PRDERR, and nonmem executable. Default: FALSE. |
epilog |
Path to user-defined script that will be sourced at completion of NONMEM run. Default value is NULL. |
dvname |
Name of the dependent variable to use as a label for the diagnostic plots. Default: DV. |
logtrans |
Whether to transform the NONMEM output variables DV, PRED, and IPRED. Default: FALSE. |
covplt |
Whether to generate covariate diagnostic plots. Default: FALSE. |
grp |
Item in
NONMEM datafile or output table file 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"). |
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 DataFile . Values are retrieved from DataFile
so they do not need to be 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 DataFile so they do not need to be 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. 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. 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". |
dosbox |
Whether to capture all MS DOS box info when using NONR on MS Windows. If set to TRUE, all output to DOS box during NONMEM run will be shown on R console. Options only functions on MS Windows and is a good diagnostic tool to use if NONMEM run fails prior to execution. Default: TRUE. |
nochecksum |
Turn nmqual checksum on or off. There is no good reason to set this to true unless MItools code development is taking place. Default: FALSE |
grid |
Whether NONMEM execution is taking place on an appropriately configured (Sun Grid Engine) Nix/Apple grid or locally. Default: FALSE |
nice |
Whether the NONMEM run directory, based on b , is
deleted or simply emptied prior to the execution of NONMEM. If
nice=TRUE , standard NONMEM files (cwtab1, *.ctl, *.lst, etc..)
are deleted but non-standard files/directories are not deleted prior
to a NONMEM execution. Using nice=TRUE will preserve .svn
directories. Default: FALSE |
Generally 0 and 1 can be used in place of FALSE and TRUE.
The plotting device is pdf().
NONR and PLOTR are used for their side effects.
Specific control stream syntax is expected when running NONR and the other functions present in the MIfuns package. The list of syntax requirements are as follows: (1) $PROB should be followed by "RUN#" then a number representing the control stream number. No commas should be used in the $PROB statement. (2) The datafile name and relative path needs to be on the first line of the $DATA record immediately following "$DATA". (3) The datafile relative path must be one directory deeper than actual, anticipating the fact that a COPY of the control stream will be exectuted from within a dynamically created SUB-directory. If 3.ctl and DATA3 share a directory, then 3.ctl should contain "$DATA ../DATA3" not "$DATA DATA3", because 3/3.ctl is the copy that will be executed, and needs to find the data in its parent directory. (4) Comments should be indicated with one semicolon (;) only. (5) The NONMEM datafile must contain a "C" column containing only C's or periods("."). (6) The *.TAB file in the “$TABLE” step must contain an EVID column for plotting to function. In the case of “$PRED” models, this can be a dummy column in the datafile. (7) The NONMEM datafile must contain a column with a header of "ID" for plotting to function correctly.
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.
Developed by Metrum Institute (Bill Knebel, Tim Bergsma, and others).
MIfuns package available from Metrum Institute
website (http://metruminstitute.org/
).