FW: Output File Format for NONMEM 7

From: Bauer, Robert Sent: Tuesday, December 16, 2008 2:25 PM To: nmusers Cc: Bauer, Robert Subject: Output File Format for NONMEM 7 Dear NONMEM Users: ICON Development Solutions (IDS) is in the process of upgrading NONMEM to incorporate new analysis methods, as well as additional output files. The format of the standard results file is also being slightly modified, with improvements to allow third party software to more easily identify portions of the result file. While NONMEM 7 will not be released until June 2009, we at IDS would like to disclose the structure of the result and output files, so that you may modify your software accordingly, in anticipation of NONMEM 7's release. The user has now the ability to request a series of classical or new estimation methods within the same problem if he so chooses. Each of the new methods produces slightly different banner text and termination status text in the standard results file. For example, an iterative two stage analysis may be requested, followed by an MCMC Bayesian method, followed by an FOCEI method. The theta, sigma, and omega results of the iterative two stage method will be passed on as initial values for the MCMC Bayesian method, to facilitate the MCMC Bayesian analysis, which in turn can supply initial values for the FOCEI method. Each of these intermittent analyses will provide output to the results file, and will be identified by unique text for that method. To allow a program to consistently find the appropriate positions in the file without having to search for specific words in the text, the results file is being augmented with special tag labels that remain constant, regardless of the method used. The tags always begin with #, followed by four letters to indicate the tag type, followed by a colon (:). The following tags are presently defined: #METH: This tag specifies that following it, on the same line, will be found a text that describes the method, for example First Order Conditional Estimation Method with Interaction. #TERM: This tag indicates that beginning on the next lines, text describes the termination status of the analysis. #TERE: This tag indicates the end of the lines describing the termination status of the analysis. Thus, a software program may transfer all lines between #TERM: and #TERE: to a summary file. #OBJT: Indicates that following it, on the same line, is the text describing the objective function, such as Minimal Value Of Objective Function. #OBJV: Indicates that following it, on the same line, is the objective function value. However, a more efficient way of extracting numerical results from the analysis is from the new raw output files (see below). #OBJS: Indicates that following it, on the same line, is the objective function standard deviation (MCMC Bayesian analysis only). However, a more efficient way of extracting numerical results from the analysis is from the new raw output files (see below). In addition to the standard results file, a raw output file will be produced that provide numerical results in a columnar format. The raw output file name is provided by the user using a new FILE= parameter added to the $EST command. A raw output file has the following format: A header line that begins with the word Table, such as: TABLE NO. 4: MCMC Bayesian Analysis: Goal Function=AVERAGE VALUE OF LIKELIHOOD FUNCTION This header line provides the analysis text (same as given on the #METH: line in the results file), followed by the goal function text (same as given on the #OBJT: line in the results file). The next line contains the column headers to the table, such as (this is actually all on one line in the file): ITERATION THETA1 THETA2 THETA3 THETA4 SIGMA(1,1) OMEGA(1,1) OMEGA(2,1) OMEGA(2,2) OMEGA(3,1) OMEGA(3,2) OMEGA(3,3) OMEGA(4,1) OMEGA(4,2) OMEGA(4,3) OMEGA(4,4) OBJ This is followed by a series of lines containing the intermittent results from each printed iteration (six significant digits), based on the PRINT= parameter setting: 10 1.73786E+00 1.57046E+00 7.02200E-01 2.35533E+00 6.18150E-02 1.82955E-01 -3.18352E-03 1.46727E-01 -4.38860E-02 2.58155E-02 1.45753E-01 -4.58791E-02 6.28773E-03 5.06262E-02 1.50017E-01 -2301.19773603667 Each of the values, up to the next to last one, occupies 13 characters, including the delimiter (in this example the delimiter is a space). The last value is the objective function, which occupies 30 characters, to allow for the largest range of objective function values, and the greatest expression of precision. The iteration number, which is the first value in every line, is typically positive, but also may be negative under the following conditions: 1) The burn-in iterations of the MCMC Bayesian analysis are given negative values, starting at -NBURN, the number of burn-in iterations requested by the user. These are followed by positive iterations of the stationary phase. 2) The stochastic iterations of the SAEM analysis are given negative values. These are followed by positive iterations of the accumulation phase. 3) Iteration -100000000 (negative one billion) indicates that this line contains the final result (thetas, omegas, and sigmas) of the particular analysis 4) Iteration -100000001 indicates that this line contains the standard errors of the final population parameters. 5) Iteration -100000002 indicates that this line contains the Eigen values of the correlation matrix of the variances of the final parameters. 6) Iteration -100000003 indicates that this line contains the condition number , lowest, highest, Eigen values of the correlation matrix of the variances of the final parameters. 7) Additional special iteration number lines may be added in future versions of NONMEM. It is hoped that with this file structure, third party software may be easily programmed to search for the line with the appropriate iteration tag number, read in the values on that line in a systematic manner into the appropriate locations, and use the values for post-analysis processing, such as graphing and additional statistical analysis. These raw output files are provided automatically, independent of the additional formatted output files that may be requested by the user using the $TABLE command. Example results and raw output files will be e-mailed to those who request it by contacting Bob Bauer at [email protected]. Suggestions on the format of the output files that would be of general use are welcome. Robert J. Bauer, Ph.D. Vice President, Pharmacometrics ICON Development Solutions Tel: (215) 616-6428 Mob: (925) 286-0769 Email: [email protected] Web: www.icondevsolutions.com