+--------------------------------------------------------------------+
| |
| $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=[numberlist] [SIRNITER=n] [SIRCENTER=n]
[IACCEPT=x] [IACCEPTL=x]
[SIRDF=n] [RANMETHOD=[n|S|m|P] ]
[SIRPRINT=n] [FILE=filename] [FORMAT=s]
[SIRTHBND=n]
[SIRMINWT=x] [SIRMAXWT=x] [SIR_CAPCORR=x]
[SIRSEED=n] [SIRCLOCKSEED=[0|1]]
[SIRPARAFILE=[filename|ON|OFF] [SIRPARAFPRINT=n]
[PRECOND=n] [PRECONDS=TOS] [PFCOND=n] [PRETYPE=n]
[FPOSDEF=n]
[CHOLROFF=n] [KNUTHSUMOFF=n]
[POSDEF=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,
ADVAN15, ADVAN16, ADVAN17, ADVAN18, 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, however, you may want to reduce ATOL (usu-
ally 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 nmfe7 command. Default is
PARAFPRINT=1.
THBND=n (NM74)
If THBND=1, 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 transforma-
tions. This is suitable during the estimation step, but may be
desirable have this off (THBND=0) for covariance assessment, and
assess partial derivatives of the objective function with respect
to the thetas themselves, or some linear transformation of these
thetas. By default THBND=1, in keeping with the behavior of ear-
lier NONMEM versions, which effectively has THBND=1. Usually
boundaries that are fairly wide will not impact how the variance-
covariance is assessed, such as when a lower bound of 0 is given,
but if you have very narrow boundaries set, then this can impact
the assessment of the variance-covariance of the estimates con-
siderably, and you may wish to set THBND=0. If no lower or upper
bounds are given to thetas in $THETA record, this option has no
impact.
SIRSAMPLE=[numberlist] (NM74)
Option SIRSAMPLE requests the Sampling-Importance-Resampling
algorithm (SIR)
(See Guide Introduction_7, "Importance Sampling of the Variance-
Covariance of the Parameter Estimates").
By default SIRSAMPLE=-1, so SIR process does not occur. SIRSAM-
PLE should be set between 300 and 10000, to indicate the number
of random samples to be generated for each of the SIRNITER itera-
tions. This will produce SIRSAMPLE importance samples, each of
which will be placed in the raw output file. As of nm75, SIRSAM-
PLE may contain a list of integers, one for each of the SRNITER
iterations (use double quotes around the list): SIRSAM-
PLE="1000,200,500" If there are fewer than SIRNITER values, the
last value in the list will be used as the SIRSAMPLE value for
the remaining iterations. Utility programs table_quant (fre-
quency 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.
SIR_CAPCORR=x (NM75)
Limit the correlation of omegas and sigmas generated form the
proposal density to have |correlation| of SIR_CAPCORR or less.
This is similar to PSN's cap_correlation option.
SIRMINWT=x (NM75)
SIRMAXWT=x (NM75)
Limit the weight range that a sample may relative to the proposal
density, to avoid extreme values. Default values are
SIRMINWT=0.001, SIRMAXWT=1000.0
SIRSEED=n (NM75)
Starting seed for SIR analysis (default=11456).
SIRCLOCKSEED=[0|1] (NM75)
If SIRCLOCKSEED=1 (default is 0), actual starting seed will be
10000*(seconds after midnight)+SEED. This allows a control
stream to produce different stochastic results for automated
replications, without the need to modify the seed value in the
control stream file in each replication.
IACCEPT=x (NM74)
The acceptance ratio acts similarly to importance sampling in EM
analysis. Default is 1.
IACCEPTL=x (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 (NM75)
By default, the format for the raw output file and all additional
output files is whatever FORMAT was specified for the $EST step.
You can change its format with the FORMAT option. s defines the
delimiter [,|s(pace)|t(ab)] followed by a Fortran format specifi-
cation. The default is s1PE12.5. For more details, see the for-
mat help item:
(See format).
See INTRODUCTION TO NONMEM 7, FORMAT=s1PE11.4
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.
SIRPARAFILE=filename
Name of the "parallel file" (the parallelization profile) that
controls parallelization during SIR sampling (distributed comput-
ing). Default file name if not specified: parallel.pnm or
parafile name specified on nmfe command.
SIRPARAFILE=ON turns on parallelization for this $COVARIANCE
record during SIR sampling.
SIRPARAFILE=OFF turns off parallelization for this $COVARIANCE
record during SIR sampling.
SIRPARAFPRINT=n (NM74)
The print iteration intervals to the parallelization log file can
be controlled by this option during parallelization of the SIR
sampling portion of the $COV step. See also $ESTIMATION record
and nmfe7 command. Default is SIRPARAFPRINT=1.
PRECOND=n (NM74)
Options PRECOND through PRETYPE affect the preconditioning of the
R Matrix.
(See Guide Introduction_7, "Preconditioning the R Matrix to
Improve Precision and Success Rate of $COV Step").
By default, PRECOND (Preconditioning cycles") is 0, and no pre-
conditioning of the R matrix is performed. When PRECOND=n, then
up to n preconditioning cycles are performed. This is used in
combination 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
(before inversion) will be evaluated in the manner of earlier
versions of NONMEM. This is strictly for comparison with earlier
versions for diagnostic purposes. If CHOLROFF=0, then a part of
the R matrix evaluation will undergo cholesky decomposition, and
if not positive definite, only then will it undergo evaluation
according to earlier versions of NONMEM. If CHOLROFF=2, then if
cholesky decomposition fails, it will be slightly adjusted to be
positive definite. The CHOLROFF=0 is the safest option, in that
the Cholesky decomposition (if positive definite) provides more
precision in evaluating the R matrix. The CHOLROFF=2 setting is
useful if you wish to increase the rate of success in obtaining
an R matrix (followed by its inverse) that could be suitable for
SIR sampling. If you use CHOLROFF=2, then positive definiteness
has been corrected before the inverse occurs, so POSDEF will have
no additional effect. If you use POSDEF, then CHOLROFF should be
0 or 1. 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.
POSDEF=n (NM75)
If POSDEF=1, then if the R matrix is not positive definite, it
will be forced positive definite, by method of shifting the ei-
genvalues by an amount slightly greater than the most negative
eigenvalue. If POSDEF=2, then R matrix is made positive definite
by making the negative valued eigenvalues approximately 1/100 of
the least positive eigenvalue. If POSDEF=3, then R matrix is made
positive definite by using the absolute values of the eigenvalues
POSDEF is 0 (no correction) by default for classical covariance
step, and 3 for EM methods.
The preconditioning method is a more sophisticated, but time-con-
suming method of making the R matrix positive definite (See PRE-
COND).
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)