___________________________________________________________________
| |
| $ESTIMATION |
|_________________________________________________________________|
MEANING: Instructions for the NONMEM Estimation Step
CONTEXT: NM-TRAN Control Record
USAGE:
$ESTIMATION [METHOD=kind] [NOINTERACTION|INTERACTION]
[NOLAPLACIAN|LAPLACIAN] [NOPOSTHOC|POSTHOC]
[PREDICTION|LIKELIHOOD|-2LOGLIKELIHOOD]
[NOFO|FO] [NOCENTERING|CENTERING]
[NOSLOW|SLOW]
[STIELTJES] [GRID=(nr,ns,r0,r1)] |
[SLOW=1|SLOW=2] |
[ZERO=list] [NONUMERICAL|NUMERICAL]
[SIGDIGITS=n1] [MAXEVALS=n2] [PRINT=n3]
[ABORT|NOABORT] [MSFO=filename]
[NOREPEAT|REPEAT]
[NOREPEAT1|REPEAT1] [NOREPEAT2|REPEAT2] |
[NOETABARCHECK|ETABARCHECK]
[NOSORT|SORT]
[THETABOUNDTEST|NOTHETABOUNDTEST] |
[OMEGABOUNDTEST|NOOMEGABOUNDTEST] |
[SIGMABOUNDTEST|NOSIGMABOUNDTEST] |
[OMITTED]
SAMPLE:
$ESTIMATION MAXEVAL=450 PRINT=5
DISCUSSION:
Optional. Requests that the NONMEM Estimation Step be implemented.
May also be coded $ESTM or $ESTIMATE. The Estimation Step obtains
parameter estimates.
OPTIONS:
METHOD=kind
Values for kind are:
0 or ZERO
Always set etas to 0 during the computation of the objective
function. Also called the "first order (FO) method." This
is the default.
1 or CONDITIONAL
Use conditional estimates for the etas during the computa-
tion of the objective function. METHOD=1 (without the
LAPLACIAN option) is also called the "first order condi-
tional estimation (FOCE) method." The conditional estimates
of the etas are referred to as Conditional Parametric Etas
(CPE).
HYBRID
Use conditional estimates for the etas during the
computation of the objective function, with the exception of
those etas listed in the ZERO option.
Cannot be used with LAPLACIAN or CENTERING.
INTERACTION
The dependence on etas of the model for intra-individual random
error is preserved in the computation of the objective function.
Cannot be used with CENTERING.
NOINTERACTION
Always set etas to 0 during the computation of the model for
intraindividual random error. This is the default.
LAPLACIAN
Use the Laplacian method, in which second derivatives with
respect to eta are used.
May only be specified with METHOD=1.
Cannot be used with $ABBREVIATED DERIV2=NO.
NOLAPLACIAN
Do not use the Laplacian method. This is the default.
PREDICTION
Indicates that Y (with NM-TRAN abbreviated code) or F (with a
user-supplied PRED or ERROR code) will serve as a prediction
variable, i.e., it will be set to a prediction. Upon simulation,
the simulated observation is possibly also being set in Y or F.
(However, the DV data item may instead be set directly to the
simulated observation.) Also, etas (if any) are population etas
only if epsilons also appear. This is the default.
LIKELIHOOD
This is designed mainly, but not exclusively, for use with non-
continuous observed responses ("odd-type data"). Indicates that
Y (with NM-TRAN abbreviated code) or F (with a user-supplied PRED
or ERROR code) will be set to a (conditional) likelihood. Upon
simulation it will be ignored, and the DV data item will be set
directly to the simulated value in abbreviated or user code.
Also etas, if any, are understood to be population etas. Epsilon
variables and the $SIGMA record may not be used. The L2 data
item may not be used.
The CONTR and CCONTR options of the $SUBROUTINES record may not L
be used. L
NONMEM cannot obtain the initial estimate for omega. If the data
are population, and MAXEVALS=0 is not coded, then METHOD=1
LAPLACE is required.
-2LOGLIKELIHOOD
Indicates that Y (with NM-TRAN abbreviated code) or F (with a
user-supplied PRED or ERROR code) is a -2 log (conditional)
likelihood. All remarks for LIKELIHOOD apply. May also be coded
-2LLIKELIHOOD.
FO
Requests that the First-Order Model be used with METHOD=1 and
CENTERING. Cannot be used with LAPLACIAN.
NOFO
Requests that the First-Order Model not be used with METHOD=1 and
CENTERING. This is the default.
CENTERING
Requests that the average conditional estimates of each eta be
constrained to be close to 0. May only be used with METHOD=1.
Not permitted with INTERACTION.
NOCENTERING
Requests that the average conditional estimates of each eta not
be constrained. This is the default.
METH=COND NOLAPLACIAN is referred to as the FOCE method.
METH=COND LAPLACE is referred to as the Laplace method.
METH=COND NOLAPLACE CENTERING is referred to as the Centering FOCE method.
METH=COND LAPLACE CENTERING is referred to as the Centering Laplace method.
STIELTJES |
Not permitted with METHOD=HYBRID. Consult with advanced users of |
NONMEM for information about this method. |
GRID=(nr,ns,r0,r1) |
Optional. May be used with STIELTJES. |
SLOW
Requests a slower method of computation. Required when either a
mixture model is used along with CENTERING, or NUMERICAL is used.
If not present, the option is automatically supplied in these two
cases. The SLOW option may have little or no effect on results
for estimation methods other than those for which it is required.
SLOW=1
Same as SLOW.
NOSLOW
Requests a faster method of computation. This is the default
(but see SLOW)
SLOW=2 |
This option is permitted with STIELTJES. |
NUMERICAL
Requests that second eta-derivatives for the Laplacian method be
obtained numerically.
NONUMERICAL
Requests that second eta-derivatives for the Laplacian method be
computed by PRED. Not permitted with the combination LAPLACIAN
and INTERACTION. Otherwise, this is the default.
ZERO=list
Required with METHOD=HYBRID. A list of indices for etas which
are fixed to zero during the Estimation Step. "list" contains
one or more integers. If more than one, they must be surrounded
by parentheses. The list must be contained entirely on one line.
The indices may be separated by commas or spaces.
POSTHOC
This option may be used when the FO method is used. After the
Estimation Step terminates, the eta values are estimated for each
individual. To estimate the etas based on the initial estimates
of THETA, OMEGA, and SIGMA (found either in the control stream or
in a model specification file), also specify MAXEVAL=0 (which
omits the Estimation Step). The conditional estimates of the
etas are referred to as Conditional Parametric Etas (CPE).
NOPOSTHOC
Etas are not estimated. This is the default with METHOD=0. May
not be used with METHOD=1.
SIGDIGITS=n1
Number of significant digits required in the final parameter
estimate. Default: 3. May also be coded NSIGDIGITS.
MAXEVALS=n2
Maximum allowable number of evaluations of the objective function
during the Estimation Step. Default: a generous number. (Each
evaluation of the objective function requires one pass through
the data set. This is also referred to as a "function evalua-
tion.") MAXEVALS=-1 may be specified when a $MSFI record is
present. It requests that NONMEM re-use the value from the pre-
vious run, and is the default with $MSFI.
MAXEVAL=0 requests that the Estimation Step be omitted. This is
useful, for example, with POSTHOC (see above).
PRINT=n3
Iteration summaries are printed for the 0th, every n3th itera-
tion, and last iteration. When n3=0, no summaries are printed.
Default: 9999 (so that summaries are printed for 0th and last
iterations).
ABORT
During the Estimation Step, NONMEM does not implement theta-
recovery when PRED sets the error return code to 1. (The PRED
error return code n is set by the statement "EXIT n [k]" in
abbreviated code, or by the statement IERPRD=n in user-supplied
code, or by PREDPP when it detects errors.) This is the default.
NOABORT
During the Estimation Step, NONMEM implements theta-recovery,
i.e., attempt to avoid values of theta which result in PRED error
return code 1.
MSFO=filename
A Model Specification File is output to a file with the given
filename. Filename may not contain embedded spaces. If filename
contains commas, semicolons, or parentheses, then it must be sur-
rounded by quotes (' or "). Filename may also contain equal
signs if it is enclosed in quotes.
Filename may contain at most 71 characters. |
If filename is the same as any option of the $ESTIMATION record,
it must be enclosed in quotes. If the $NONPARAMETRIC record is
present and also specifies the MSFO option, the filename is
required on the record which appears first in the control stream.
If filename is present on both, it must be the same. If the
filename is omitted on the second of the two records, the MSF
option must be the final option on that record. Default: If the
MSFO option is not used, no MSF is output.
If a MSFO is output, then the iteration estimates may also be seen in
the original parameterization for those iterations whose summaries
appear in intermediate printout. These estimates may be found in file
INTER, which will exist only during the duration of the run.
When MAXEVAL=0 and the Covariance Step is implemented, the MSFO option
may also be used, and then a model specification file will be output
which will include information from the Covariance Step and from the
input model specification file concerning the earlier Estimation Step
(in this case there must be an input model specification file).
(See model_specification_file).
NOREPEAT
The estimate obtained at the end of the minimization search is
taken to be the final parameter estimate. This is the default.
Cannot be used with STIELTJES. |
REPEAT
The search is repeated with the initial estimates being the final
estimates from the first search and with new UCP, so that a UCP
value of 0.1 now corresponds to a final estimate from the first
search.
Cannot be used with STIELTJES. |
NOREPEAT1 |
The estimate obtained at the end of the search of the first stage |
of the Stieltjes method is taken to be the final parameter esti- |
mate at the first stage. This is the default. May only be used |
with STIELTJES. |
REPEAT1 |
The search of the first stage of the Stieltjes method is repeated |
with the initial estimates being the final estimates from the |
first search and with new UCP, so that a UCP value of 0.1 now |
corresponds to a final estimate from the first search. May only |
be used with STIELTJES. |
NOREPEAT2 |
The estimate obtained at the end of the serach of the second |
stage of the Stieltjes method is taken to be the final parameter |
estimate at the second stage. This is the default. May only be |
used with STIELTJES. |
REPEAT2 |
The search of the second stage of the Stieltjes method is |
repeated with the initial estimates being the final estimates |
from the first search and with new UCP, so that a UCP value of |
0.1 now corresponds to a final estimate from the first search. |
May only be used with STIELTJES. |
NOETABARCHECK
The P-value associated for the etabar statistic (See etabar)
relates to a hypothesis test that the true etabar is 0. This is
the default.
ETABARCHECK
There is an etabar statistic (See etabar) from a previous prob-
lem, and the P-value associated for the etabar statistic with the
problem at hand relates to a hypothesis test that the true etabar
is the same as that with the previous problem.
NOSORT
Individual contribution to the objective function value and indi-
vidual contributions to the gradients are summed in the order in
which the individual records appear in the NONMEM data set, as
was done prior to NONMEM VI. This is the default.
SORT
Individual contribution to the objective function value and indi-
vidual contributions to the gradients are sorted before they are
summed, so that smaller numbers are summed before larger numbers.
THETABOUNDTEST, OMEGABOUNDTEST, SIGMABOUNDTEST |
With NONMEM VI, the estimation step sometimes terminates with the |
message |
PARAMETER ESTIMATE IS NEAR ITS DEFAULT BOUNDARY. |
These options request that the "default boundary test" be per- |
formed for THETA, OMEGA, and SIGMA, respectively. THETABOUNDTEST |
may also be coded TBT or TBOUNDTEST; OMEGABOUNDTEST may also be |
coded OBT or OBOUNDTEST; SIGMABOUNDTEST may also be coded SBT or |
SBOUNDTEST. These options are the defaults. |
NOTHETABOUNDTEST, NOOMEGABOUNDTEST, NOSIGMABOUNDTEST |
Instructs NONMEM to omit the "default boundary test" for this |
type of variable, i.e., to behave like NONMEM V in this regard. |
Any option listed above may be preceded by "NO". The THETA, |
OMEGA, and SIGMA choices are independent of each other. E.g., it |
is possible to specify NOOBT (to prevent the "default OMEGA boun- |
dary test") and permit both the "default THETA boundary test" and |
"default SIGMA boundary test". |
OMITTED
The Estimation Step is not implemented.
REFERENCES: Guide I Section C.3.5.1
REFERENCES: Guide II Section E, F
REFERENCES: Guide IV Section III.B.14, IV.G
REFERENCES: Guide V Section 9.4.1,, 13.2
REFERENCES: Guide VII Section I, II, III
Go to main index.
Created by nmhelp2html v. 1.0 written by Niclas Jonsson (Modified by AJB 5/2006,11/2007)