NONR {MIfuns}R Documentation

Run NONMEM and create diagnostic plots

Description

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.

Usage

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)

Arguments

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

Details

Generally 0 and 1 can be used in place of FALSE and TRUE.

The plotting device is pdf().

Value

NONR and PLOTR are used for their side effects.

Note

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.

Author(s)

Developed by Metrum Institute (Bill Knebel, Tim Bergsma, and others).

References

MIfuns package available from Metrum Institute website (http://metruminstitute.org/).

See Also

CWRES,compute.cwres


[Package MIfuns version 3.2.9 Index]