+--------------------------------------------------------------------+
| |
| ADDITIONAL_OUTPUT_FILES |
| |
+--------------------------------------------------------------------+
MEANING: NONMEM Additional Output files
CONTEXT: NONMEM Output Files
DISCUSSION:
With NONMEM 7, a NONMEM run produces several additional output files.
These provide a more efficient way of extracting numerical results
from the analysis than by obtaining them from the NONMEM report file.
(See raw_output_file).
Names of the files start with "root", where root is the root name (not
including extension) of the NM-TRAN control stream file given at the
nmfe command line, or root="nmbayes" if the control stream file name
is not passed as an argument to the NONMEM executable. In this exam-
ple the root is myexample, and NONMEM 7.4 is invoked.
nmfe74 myexample.ctl myexample.res
The files have names with extensions (suffixes) .ext, .cov, .clt,
.coi, .cor, .cpu, .phi, .phm, .grd, .shk, .shm, .cnv, smt, .rmt, .vpd,
.ets, .bfm. In this example, they will be myexample.cov, myexam-
ple.coi, etc.
Each type of file accumulates information from each step that gener-
ates the type of output in question.
The first two lines of each file is the same. First is a header line
that begins with the word TABLE, such as:
TABLE NO. n:
These tables are not related to the ones produced by the $TABLE
record. The value of n is incremented each time the Estimation Step
is implemented, i.e., once per $ESTIM record, when MAXEVAL is not 0
and $EST is not omitted. The $EST records may be in the same problem,
or in subsequent problems. If $COV is present in a problem without
$EST (e.g., when $MSFI is used), then n is also incremented.
Next on the header line is the analysis text (same as given on the
#METH: line in the report file), e.g., "First Order".
Also on this line are:
Problem=1 Subproblem=0 Superproblem1=0 Iteration1=0
Superproblem2=0 Iteration2=0
The values of Problem, Subproblem, Superproblem1, Iteration1, Super-
problem2, Iteration2 are the same values as would be found in the fol-
lowing variables in modules during the run:
IPROB IREP S1NUM S1IT S2NUM S2IT
The second line contains the column headers for the current additional
file, all on one line.
Options NOTITLE and NOLABEL and FORMAT of the $ESTIMATION record can
be used to supress the first and/or second lines, and to modify the
format of the values in the table. They apply to raw and additional
output files, but only for the current Estimation Step. The options
must be re-specified with each $EST record.
The additional output files are:
root.ext
Always. (See raw_output_file).
root.phi
Always. Individual phi parameters (phi(i)=mu(i)+eta(i), for ith
parameter), and their variances phc(,). For parameters not MU
referenced phi(i)=eta(i). When a classical method is performed
(FOCE, Laplace), then mode of posterior eta(i) are printed out,
along with their Fisher information (first order expected value
for FOCE, second order for Laplace) assessed variances etc(,).
For ITS, these parameters are the modes of the posterior density,
with first-order approximated expected variances (or second order
variances if $EST METHOD=ITS LAPLCE is used). For IMP, IMPMAP,
SAEM methods, they are the Monte Carlo evaluated conditional mean
parameters and variances of the parameters under the posterior
density. For MCMC Bayesian, they are random single samples of
phi(), as of the last position. Their variances are zero. Indi-
vidual objective function values (obji) are also produced. As of
NONMEM 7.4, if $EST PHITYPE=1 is specified, then conditional mean
etas are reported in the phi table. regardless of the analysis
method.
root.iph (NM75)
As of nm75, samples of phi/eta are collected at each BAYES itera-
tion, and summarized to provide conditional mean phi and phc() in
the root.phi table, as described above. By default, the individ-
ual phi values from each iteration are not stored. However, if
you set
$EST ... BAYES_PHI_STORE=1
then phi and eta values from each BAYES iteration will be stored
in root.iph. For non-mixture problems, only records of SUBP=0 are
recorded, as there are no sub-population divisions. For mixture
problems, the SUBP=0 records contain the composite phis and etas
(the average of these across all non-negative iterations are in
the root.phi table), and the SUBP>0 records contain the phis and
etas appropriate to each sub-population SUBP (the average of
these across all non- negative iterations are in the root.phm ta-
ble). The root.iph file can become quite large, so it should be
used only on the final analysis.
root.phm (NM72)
Individual phi/eta/obji parameters per sub-population. This file
is only produced in $MIXTURE problems. As of nm75, for MCMC
Baysian analysis, the items listed in this table consist of the
average values among all the iterations during the stationary
distribution phase. Before nm75, the values consisted of values
from the last MCMC iteration.
root.shk (NM72)
This file presents composite eta shrinkage and epsilon shrinkage
information, the same as given in the NONMEM report file between
the #TERM: and #TERE: tags, but in rows/column format, and with
adjustable formatting.
(See shrinkage).
root.shm (NM73)
This file is a shrinkage map describing which etas were included
or excluded in the eta shrinkage assessment. (See shrinkage).
root.grd (NM72)
Gradient values for classical NONMEM methods. Always.
root.xml (NM72)
An XML markup version of the contents of the NONMEM report file.
The rules by which it is constructed are given in output.xsd and
output.dtd.
root.cov
Full variance-covariance error matrix of thetas, sigmas, and
omegas. Same as "COVARIANCE MATRIX OF ESTIMATE" in the NONMEM
report except that it is full (NONMEM displays only the lower
triangle), elements that are fixed or not estimated are displayed
as 0 (NONMEM displays them as .....), and, when the data are
individual, sigma is displayed as 0 (NONMEM does not display
sigma at all.) Only generated if the $COVARIANCE record is
present.
(See covariance matrix of estimate).
(See Covariance_Output_files).
(See order_option).
root.clt (NM74)
The lower-triangular portion of the variance-covariance of the
parameter estimates reported in root.cov. This is provided for
easier pasting of the information as theta priors for a subse-
quent analysis. Only generated if the $COVARIANCE record is
present.
root.cor
Full correlation matrix of thetas, sigmas, and omegas. Same as
"CORRELATION MATRIX OF ESTIMATE", except as described for
root.cov.
(See correlation matrix of estimate).
root.coi
Full inverse covariance matrix (Fischer information matrix) for
thetas, sigmas, and omegas. Same as "INVERSE COVARIANCE MATRIX
OF ESTIMATE" except as described for root.cov.
root.cnv (NM72)
Convergence information for the Monte Carlo/EM methods, if
CTYPE>0.
(See raw_output_file).
root.smt (NM72)
Contains the S matrix, if $COV step failed.
root.rmt (NM72)
Contains the R matrix, if $COV step failed.
root.imp (NM73)
Produced if the user selects importance sampling with option IAC-
CEPT=0.0. Contains the final IACCEPT and DF values that NONMEM
selected for each subject.
root.npd (NM73)
For NONPARAMETRIC method. Each row contains information about a
support point.
root.npe (NM73)
For NONPARAMETRIC method. The expected value etas and expected
value eta covariances (ETC) are listed for each problem or sub-
problem.
root.npi (NM73)
For NONPARAMETRIC method. The individual probabilities are
listed. Each row contains information about a support point.
root.npl (NM74)
For NONPARAMETRIC method. The individual data likelihoods (not
including the parameter density) are listed in this file.
root.fgh (NM73)
This file is produced if the user selects $EST NUMDER=1 or
NUMDER=3. The file lists the numerically evaluated derivatives
of Y with respect to eta, where
F=Y (the prediction)
G(I,1)=partial Y with respect to eta(i))
G(I,J+1)=Second derivatives of Y with respect to eta(i),eta(j)
H(I,1)=partial Y with respect to eps(i)
H(i,j+1)=partial Y with respect to eps(i),eta(j)
The values are those used in the Estimation Step. Values of F
are computed by PRED with eta=0 if METHOD=0 is used; otherwise
they are computed with non-zero etas: the Conditional (CPE) etas,
empirical bayes estimates (EBE), mode a posteriori (MAP) esti-
mates) or conditional mean etas, depending on the Estimation
Method. Values of G are computed by NONMEM via finite differ-
ences using these values of F and eta. Values of H are computed
by NONMEM with the same values of F and eta if INTERACTION is
specified; otherwise, they are computed with eta=0.
root.agh (NM73)
This file is produced if the user selects $EST NUMDER=2 or
NUMDER=3. The file lists the analytically evaluated derivatives
of Y with respect to eta. The format and order is the same as
file root.fgh. The values are those returned by subroutine PRED
in arguments F, G, and H. These are 0 if not computed by PRED.
(E.g. second derivatves are not computed analytically with a
method other than LAPLACIAN.) Values in root.agh correspond
exactly to those in root.fgh. That is, values of F and G are
from calls to PRED with eta=0 or with non-zero etas, as described
above. Values of H are from calls to PRED with the same values
of eta if INTERACTION is specified; otherwise, they are from
calls to PRED with eta=0, regardless of the Estimation method.
root.vpd (NM74)
This file is produced if the $TABLE file option VARCALC=1 or VAR-
CALC=2 is used. It is the full variances- covariances among all
user-defined and PREDPP parameters. The FORMAT used for this
file is that defined in the $EST record.
root.ets (NM74)
As of NM74, one can obtain random samples of individual etas, and
uses these for covariate and model diagnostics. $EST option
ETASAMPLES=1 causes individual ISAMPLE random eta samples per
subject, to be written to root.ets, where root is the root name
of the control stream file.
See "Stochastic Approximation Expectation Maximization (SAEM)
Method" in Guide Introduction_7.
root.bfm (NM75)
When OFVTYPE=8 during optimal design ($DESIGN OFVTYPE=8) the
progress of average individual conditional variances (average
empirical Bayes conditional variance) are shown in the root.bfm
file (where root is name of control stream file), and the final
one on the -1000000000 line, during an optimization. The RAW file
(by default named root.ext) which shows only the starting, and
final values of the standard errors of population parameters, as
extra information.
root.cpu (NM73)
The cpu time in seconds is reported in this file. It is an accu-
rate representation of the computer usage, whether single or par-
allel process. The same problem when run singly or in parallel
will report a similar cpu time. This is in contrast with elapsed
time, which is improved with parallelization.
With NONMEM 7.3 and higher, the $THETAI and $THETAR records may be
used to transform initial and final estimates of THETA, respectively.
This will affect values in the .ext, .cov, etc. files
(See $thetai, $thetar)
REFERENCES: Guide Introduction_7
Go to main index.
Created by nmhelp2html v. 1.0 written by Niclas Jonsson (Modified by AJB 5/2006,11/2007,10/2012)