+--------------------------------------------------------------------+
| |
| $COVARIANCE,$COVR |
| |
+--------------------------------------------------------------------+
MEANING: Instructions for NONMEM Covariance Step
CONTEXT: NM-TRAN Control Record
USAGE:
$COVARIANCE [SPECIAL] [MATRIX=] [PRINT=[E][R][S]
[COMPRESS]
[SLOW|NOSLOW|FAST]
[TOL=n] [ATOL=n]
[SIGL=n] [SIGLO=n]
[NOFCOV]
[PARAFILE=[filename|ON|OFF] [PARAFPRINT=n]
[THBND=n]
[SIRSAMPLE=n] [SIRNITER=n] [SIRCENTER=n]
[IACCEPT=n] [IACCEPTL=n]
[SIRDF=n] [RANMETHOD=[n|S|m|P] ]
[SIRPRINT=n] [FILE=filename] [FORMAT=s]
[SIRTHBND=n]
[PRECOND=n] [PRECONDS=TOS] [PFCOND=n] [PRETYPE=n]
[FPOSDEF=n]
[CHOLROFF=n] [KNUTHSUMOFF=n]
[RESUME]
[CONDITIONAL|UNCONDITIONAL]
[OMITTED]
SAMPLE:
$COVARIANCE
DISCUSSION:
Optional. Requests that the NONMEM Covariance Step be implemented.
This step outputs: standard errors, covariance matrix, inverse covari-
ance matrix, and the correlation form of the covariance matrix. May
also be coded $COVR.
If $COV is specified, then for IMP, IMPMAP, and ITS methods, standard
error information will be supplied for every $EST statement. Standard
error information for the classical methods (METHOD=0, METHOD=1) will
be given only if they are the last estimation method, and only if NOF-
COV is not specified.
OPTIONS:
SPECIAL
The special computation will be used in the Covariance Step with
a recursive PRED subroutine. A recursive PRED subroutine is such
that, with single-subject data, the PRED computation with a data
record depends on information passed to it with any of the previ-
ous data records. This is the default when PREDPP is used.
MATRIX=c
Specifies that the covariance matrix will be different from the
default (R sup -1 S R sup -1). MATRIX=R requests that 2 times
the inverse R matrix be used. MATRIX=S requests that 4 times the
inverse S matrix be used. (R and S are two matrices from sta-
tistical theory, the Hessian and Cross-Product Gradient matri-
ces, respectively.) With MATRIX=R the standard errors will be |
more consistent with other nonlinear regression software imple- |
mentations. MATRIX=R should not be used with option SPECIAL.
MATRIX has no relevance to the Covariance step results for a
BAYES method.
PRINT=[E][R][S]
Additional outputs will be printed besides the defaults. E:
print the eigenvalues of the correlation matrix. R: print the
matrix .5*R. S: print the matrix .25*S. PRINT=R (or S) is not
needed with MATRIX=R (or S).
COMPRESS
Covariance Step arrays are printed in compressed format, even if
their size is such that NONMEM would normally print them in the
usual format.
SLOW Requests a slower method of computation. Required when either a
mixture model was used along with CENTERING on the $ESTIMATION
record, or NUMERICAL was used on the $ESTIMATION record. If not
present, the option will be automatically supplied in these two
cases.
NOSLOW
Requests a faster method of computation. This is the default
(but see SLOW). |
FAST (NM74) |
This is equivalent to FAST for the $EST record. record. If $EST |
FAST is set, then $COV will be set to FAST, unless SLOW or NOSLOW |
is specified.
TOL=n (NM72)
Tolerance. Used only with General Nonlinear (differential equa-
tion solver) ADVAN's. Sets NRD=TOL. By default, the value set on
$SUBROUTINES record (or $TOL or TOL subroutine) is used. If TOL
is coded on $COVARIANCE, it overides the default. With NONMEM
74, this feature is deprecated. A user-supplied TOL subroutine
should test NM_STEP and set NRD accordingly.
TOL has no relevance to the Covariance step results for a BAYES
method.
ATOL=n (NM72)
Absolute tolerance. Used only with ADVAN9, ADVAN13, ADVAN14, and
ADVAN15, for which TOL is a relative tolerance. Sets ANRD=ATOL.
The default is 12 (that is, accuracy is 10**(-12)). Usually the
problem runs quickly when using this setting. On occasion, how-
ever, you may want to reduce ATOL (usually set it equal to that
of TOL), and improve speeds of up to 3 to 4 fold.
By default, the value set on $SUBROUTINES record (or $TOL or TOL
subroutine) is used. If ATOL is coded on $ESTIMATION, it over-
rides the default for that step. If ATOL is coded on $COVARI-
ANCE, it overrides $ESTIMATION and/or the default for that step.
With NONMEM 74, this feature is deprecated. A user-supplied TOL
subroutine should test NM_STEP and set ANRD accordingly.
SIGL=n SIGLO=n (NM72)
These options may be used to specify different values for the
Covariance step. The step size for evaluating the R matrix (cen-
tral difference second derivative) is set to SIGL/4. If only the
S matrix is evaluated (central difference first derivative), the
step size is set to SIGL/3. SIGLO is the precision to which
individual etas are optimized. Classical NONMEM methods in par-
ticular often require a different significant digits level of
evaluation (usually more stringent) during the Covariance step
than during Estimation Step. For example, during the Estimation
step, NSIG=2, SIGL=6, TOL=6 may be sufficient, but during the
Covariance step, you may need SIGL=12 TOL=12 to avoid positive
definiteness issues.
By default, values specified on the $ESTIMATION record are used.
(See $ESTIMATION).
SIGL and SIGLO have no relevance to the Covariance step results
for a BAYES method.
NOFCOV (NM72)
No $COV step for any classical estimation steps. This would be
useful if you wanted EM estimation analyses performed, and a
final FOCE analysis performed, but did not want the program to
spend time on standard error assessments for FOCE, which can take
a long time relative to the other methods.
PARAFILE=filename
Name of the "parallel file" (the parallelization profile) that
controls parallelization (distributed computing). Default file
name if not specified: parallel.pnm or parafile name specified on
nmfe command.
PARAFILE=ON turns on parallelization for this $COVARIANCE record.
PARAFILE=OFF turns off parallelization for this $COVARIANCE
record.
PARAFPRINT=n (NM74)
The print iteration intervals to the parallelization log file can
be controlled by this option during parallelization of the $COV
step. See also $ESTIMATION record and nmfe74 command. Default
is PARAFPRINT=1.
THBND=n (NM74)
By default (THBND=0), any theta boundaries specified in the
$THETA record causes NONMEM to impose a non-linear transformation
of the theta parameters so that the transformed parameters may
vary from -infinity to infinity. It does this with logistic
transformations. This is suitable during the estimation step,
but it may be desirable to turn this off for covariance assess-
ment, and assess partial derivatives of the objective function
with respect to the thetas themselves, or some linear transforma-
tion of these thetas. Set THBND=1 to do this. If no lower or
upper bounds are given to thetas in $THETA record, this option
has no impact.
SIRSAMPLE=n (NM74)
Option SIRSAMPLE requests the Sampling-Importance-Resampling
algorithm (SIR) (See NONMEM 74 Guide, "Importance Sampling of the
Variance-Covariance of the Parameter Estimates"). By default
SIRSAMPLE=-1, so SIR process does not occur. SIRSAMPLE should be
set between 300 and 10000, to indicate the number of random sam-
ples to be generated. This will produce SIRSAMPLE importance
samples, each of which will be placed in the raw output file.
Utility programs table_quant (frequency and quantile sorting) and
table_resample (resampling) may be used to analyze $COV Sampling-
Importance-Resampling data.
SIRNITER=n (NM74)
The number of times SIR sampling should occur. Default is 1.
SIRCENTER=n (NM74)
Where the sampling (proposal) density is to be centered. On the
first iteration, the mean of the sampling density is at the esti-
mate. On subsequent iterations, the mean of the sampling density
is at the estimate (SIRCENTER=0) or at the mean of the (trans-
formed) samples of the previous iteration (SIRSAMPLE=1). Default
is 0.
IACCEPT=n (NM74)
The acceptance ratio acts similarly to importance sampling in EM
analysis. Default is 1.
IACCEPTL=n (NM74)
IACCEPTL=0 (NM74) Default is 1. The IACCEPTL option performs the
same as listed for IACCEPTL in "Monte Carlo Importance Sampling
EM". Default is 0.
SIRDF=n (NM74)
The proposal density is to be a t distribution with n degrees of
freedom. Default is 0, a normal density.
RANMETHOD=[n|S|m|P] (NM74)
See the corresponding option of the $ESTIMATION record for impor-
tance sampling in EM analysis.
SIRPRINT=n (NM74)
Set the console print iterations interval. This does not impact
the iterations listed in the raw output file. Default SIR-
PRINT=0.
FILE=filename (NM74)
By default, the raw output file is whatever was listed in the
$EST step, or root.ext, where root is the root name of the con-
trol stream file. You can re-direct SIR sample listings to an
alternative file with this option.
FORMAT=s (NM74)
By default, the raw output file format is whatever was listed in |
the $EST step, or s1PE12.5. You can change its format with the
above option.
SIRTHBND=n (NM74)
As with the deterministic covariance assessment step, by default
the transformed parameters are sampled, so that no sample is
below the $THETA lower bound specification, and no higher than
the $THETA upper bound specification. To allow a boundariless
search in the original theta domain, set SIRTHBND=1. You should
also set THBND=1, so that the deterministc covariance matrix used
as the proposal density is also not hindered or contorted by the
boundaries. Default is the value of THBND, which in turn is 0 by
default.
PRECOND=n (NM74)
Options PRECOND through PRETYPE affect the preconditioning of the
R Matrix (See the NONMEM 74 Guide, "Preconditioning the R Matrix
to Improve Precision and Success Rate of $COV Step"). By
default, PRECOND (Preconditioning cycles") is 0, and no precondi-
tioning of the R matrix is performed. When PRECOND=n, then up to
n preconditioning cycles are performed. This is used in combina-
tion with the PFCOND setting.
PRECONDS=TOS (NM74)
By default, if preconditioning is performed, it is done on Thetas
(T), Omegas (O), and Sigmas(S). Specify PRECONDS (Preconditioning
types)=T to do only thetas, PRECONDS=TO to do only thetas and
omegas, etc.
PFCON=n (NM74)
PFCOND means 'forced' precondition cycles. Preconditioning occurs
exactly PFCOND times, without testing if the R matrix is positive
definite or not on each preconditioning cycle. On the remaining
PRECOND-PFCOND cycles, the R matrix is tested for positive defi-
niteness, and upon success, will terminate the preconditioning
cycles. Default is PFCOND=0.
PRETYPE=n (NM74)
By default PRETYPE(preconditioning type)=0 and the R matrix cor-
rector is V*square_root(eigenvalue). If you set PRETYPE=1, then
the corrector is V*square_root(eigenvalue)*Vtranspose. If you set
PRETYPE=2, then the corrector is the correlation version of PRE-
TYPE=1.
FPOSDEF=n (NM74)
By default FPOSDEF(forced positive definite)=0. If FPOSDEF=1,
then if the Rmatrix is not positive definite, it will be forced
positive definite. If PRECOND>0, this will occur after the PRE-
CONDth try.
CHOLROFF=n (NM74)
If CHOLROFF is set to 1, then one part of the R matrix evaluation
will be evaluated in the manner of earlier versions of NONMEM.
This is strictly for comparison with earlier versions for diag-
nostic purposes. Default is 0.
KNUTHSUMOFF=n (NM74)
In NONMEM 7.4, the Knuth summing method is used to allow the most
accurate summation of individual objective function values, even
with large variations in values of the individual objective func-
tion. To turn this off, and allow a standard summation (not rec-
ommended except for comparison purposes from earlier versions),
set KNUTHSUMOFF=1. If KNUTHSUMOFF was set in the $EST step, but
not in the $COV step, the KNUTHSUMOFF value of the last $EST
record will be used. Default is 0.
CONDITIONAL
The Covariance Step is implemented, but only when the Estimation
Step terminates successfully (in this run or in a run continued
via $MSFI). This is the default.
UNCONDITIONAL
The Covariance Step is implemented regardless of how the Estima-
tion Step terminates (in this run or in a run continued via
$MSFI).
RESUME (NM73)
If MSFO=msfile was specified in the Estimation Step for the
FO/FOCE/Laplace method and analysis was interrupted during the
Covariance Step, then the Covariance Step may be resumed where it
was interrupted in a subsequent problem. Use the $MSFI record to
specify the MSFO file of the interrupted analysis, and the RESUME
option of the $COV record:
$MSFI=msfile
...
$COV RESUME
OMITTED
The Covariance Step is not implemented.
EXAMPLE:
$COV UNCONDITIONAL TOL=10 SIGL=10 SIGLO=11
REFERENCES: Guide IV Section III.B.15
REFERENCES: Guide V Section 9.4.2, 10.6
Go to main index.
Created by nmhelp2html v. 1.0 written by Niclas Jonsson (Modified by AJB 5/2006,11/2007,10/2012)