NONMEM Users Network Archive

Hosted by Cognigen

FW: Output File Format for NONMEM 7

From: Bauer, Robert <Robert.Bauer>
Date: Tue, 16 Dec 2008 15:52:50 -0500

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 Robert.Bauer
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: Robert.Bauer
Web: www.icondevsolutions.com

 

 

 

ICON plc made the following annotations.
-------------------------------------------------------------------------=
-----
This e-mail transmission may contain confidential or legally privileged i=
nformation
that is intended only for the individual or entity named in the e-mail ad=
dress. If you
are not the intended recipient, you are hereby notified that any disclosu=
re, copying,
distribution, or reliance upon the contents of this e-mail is strictly pr=
ohibited. If
you have received this e-mail transmission in error, please reply to the =
sender, so that
ICON plc can arrange for proper delivery, and then please delete the mess=
age.
Thank You,
ICON plc
South County Business Park
Leopardstown
Dublin 18
Ireland
Registered number: 145835

Received on Tue Dec 16 2008 - 15:52:50 EST

The NONMEM Users Network is maintained by ICON plc. Requests to subscribe to the network should be sent to: nmusers-request@iconplc.com.

Once subscribed, you may contribute to the discussion by emailing: nmusers@globomaxnm.com.