+--------------------------------------------------------------------+
| |
| TNPRI |
| |
+--------------------------------------------------------------------+
MEANING: TNPRI subroutine
CONTEXT: NONMEM utility routine
USAGE:
USE SIZES, ONLY: ISIZE,DPSIZE
INTEGER (KIND=ISIZE) :: IFND,MODE,ITYP,NSAM,ISS,IVAR
REAL (KIND=DPSIZE) :: PLEV
REAL (KIND=DPSIZE) :: CNT
REAL (KIND=ISIZE) :: ICALL
CALL TNPRI (IFND,MODE,ITYP,PLEV,NSAM,ISS,IVAR,CNT)
DISCUSSION:
The model parameters THETA, OMEGA and SIGMA parameters may be con-
strained in various ways. Those parameters whose values are not fixed
are transformed in a one-to-one manner to parameters whose values are
not at all constrained a priori (the "unconstrained parameters", or
UCP). The user-written PRIOR subroutine allows a penalty function
based on a frequency prior to be specified and added to the -2log
likelihood function (Gisleskog et al, JPP, 2002, p. 473-505). This
function serves as a constraint on the estimates of THETA, OMEGA and
SIGMA and thus as a way for stable estimates to be obtained with
insufficient data. TNPRI may be called by PRIOR. (See prior). It
computes a penalty function based on a frequency prior that has a mul-
tivariate normal form for all the UCP. The one-to-one transformation
between THETA, OMEGA and SIGMA and the UCP induces a frequency prior
for THETA, OMEGA and SIGMA itself. This latter form is called the
"transformed normal" form.
Both forms have the same parameters, which are called "hyperparame-
ters". The values of the hyperparameters are produced with a prior
NONMEM problem (called the "prior problem") used to analyze a prior
data set. Thus the frequency prior has an empirical nature. The
prior problem should have implemented the Covariance Step (the Estima-
tion Step could have been implemented in yet an earlier problem).
Whenever a problem implements the Covariance Step and a model specifi-
cation file has been output, this file automatically contains informa-
tion - referred to as the "prior information", and including values
for the hyperparameters - which can be used when TNPRI is used in a
subsequent problem.
The abilty to use TNPRI suggests that with any serious analysis under-
taken in the future, though it may not be necessary to save the data
that were analyzed, a model specification file should be produced and
safely stored along with a control stream showing the particulars that
gave rise to this file. There is a special way to input the prior
information from the model specification file for its use with a sub-
sequent application of TNPRI. (Alternatively, a NONMEM control stream
may consist of multiple problems, where one problem (A) uses TNPRI,
and the prior problem appears as an earlier problem (B) in the same
control stream. The prior information from problem B can be available
to problem A without the need to use a model specification file.)
When TNPRI is used during a Simulation Step, it produces a random
value of the vector of all model parameters (whose values are not
fixed in the parameter records) from the frequency prior. (See Simu-
lation example). (See tnpri example). If TNPRI is used during a
given problem at ICALL=2, it should not be used during the same prob-
lem at ICALL=4, and vice-versa.
TNPRI may be used at ICALL=0 or ICALL=1, in which case only the values
of its input arguments are checked. If it is not used at ICALL=0 or
ICALL=1, then the first time it is used at ICALL=2 or ICALL=4, check-
ing will occur.
Do not use TNPRI with the new $ESTIMATION methods of NONMEM 7.
Input argument:
IFND
0: Indicates that a prior problem has been specified either ear-
lier in the current control stream or in a previously run control
stream, and that this problem has output a model specification
file. The prior information will have automatically been stored
in the model specification file. The prior problem should have
implemented the Covariance Step (which should have computed
either the default variance-covariance matrix or two times the
inverse of the R matrix). The current control stream should con-
sist of at least two problems: the problem that uses TNPRI and a
preceeding problem that serves only to input the prior informa-
tion from the model specification file, such as the following:
$PROB READ THE MODEL SPECIFICATION FILE
$DATA data
$INPUT ID TIME AMT DV TYPE SS II
$MSFI msf1 ONLYREAD
This simple problem (B) should be the last problem in the current
control stream that appears before the problem using TNPRI (prob-
lem (A)) and inputs a model specification file. The problem
specification should not include any task records, but it may
include e.g. a $SUBROUTINES record and/or abbreviated code, if
problem B is the first problem in the control stream, and these
elements will be needed for a subsequent problem. If problem A
inputs a model specification file msf2, any prior information in
msf2 will be ignored. If problem A outputs a model specification
file msf3 and implements the Covariance Step, the prior informa-
tion stored in msf3 is based not only on the data being analyzed,
but also on the prior information in msf1.
1: Indicates that along with the current problem (with which
TNPRI is being used), a prior problem has been specified earlier
in the same control stream. The prior problem is taken to be the
last problem in the control stream that appears before the cur-
rent one and that implements the Covariance Step (which should
have computed either the default variance-covariance matrix or
two times the inverse of the R matrix).
MODE
Discussion: In any NONMEM problem specification, all of the last
contiguously listed parameters on the $THETA record, whose values
on this record are fixed, and assuming the value of the very last
parameter itself is fixed, are called the "terminal fixed THETA
parameters". There may be no such parameters. E.g. if the
$THETA record is
$THETA 3.1 FIX 6.3 .01 400 FIX 7 FIX 90 FIX
then THETA parameters 4-6 are the terminal fixed THETA parame-
ters. If the record is
$THETA 3.1 FIX 6.3 .01 400 FIX 7 FIX 90
then there are no terminal fixed THETA parameters, because the
value 90 of the very last parameter is not fixed. Similarly, all
the last contiguous fixed parameters in OMEGA (SIGMA), assuming
the values in the very last block set are fixed, are called the
"terminal fixed OMEGA (SIGMA) parameters". (Recall that in a
diagonal $OMEGA record, all the values form separate block sets.)
There are some rules concerning the parameter records of a NONMEM
control stream that relate the parameters of the prior problem to
those of the current problem:
I. With the exception of the terminal fixed THETA parameters in
the prior problem, which are altogether ignored in the current
problem, the THETA parameters of the prior problem must be the
first THETA parameters listed in the $THETA record of the current
problem, whether or not their values are fixed in the prior prob-
lem.
II. The order of these first THETA parameters on the $THETA
record must be the same as that in the $THETA record of the prior
problem. The initial estimates of these parameters need not be
the same, but any upper or lower bounds must be the same.
III. Among the first THETA parameters, values that are fixed on
the $THETA record of the prior problem must also be fixed on the
$THETA record of the current problem, although the values need
not be the same, but not vice-versa; see discussion below con-
cerning parameter interpretation.
IV. THETA parameters peculiar to the current problem may be
listed at the end of the $THETA record of the current problem,
after the parameters that are shared between the prior and cur-
rent problems.
E.g. if the $THETA record with the prior problem is
$THETA 3.1 FIX 6.3 (0,.01) 400 FIX 7 FIX 90 FIX
then the $THETA record with the current problem may be
$THETA 10 FIX 7.0 (0,.03) 80.2 100.8
in which case the values 80.2 and 100.8 are the values of the
THETA parameters that are peculiar to the current problem. The
2nd and 3rd parameters are used in both prior and current prob-
lems, but have different values in the two problems. The first
parameter may be used in the current problem, in which case its
value is fixed to 10.
The same rules apply to the $OMEGA and $SIGMA records of the cur-
rent problem.
A model specification file from a previous instance of the cur-
rent problem may be used, as usual, providing that if with the
previous instance, parameter records were used, the above rules
were followed.
Parameter Interpretation: The prior information concerns all
parameters appearing in the prior problem whose values are not
fixed in that problem. However, a parameter with a nonfixed
value in the prior problem may have a fixed value in the current
problem, and this gives rise to some ambiguity. Such a parameter
may have an interpretation in the prior problem that remains
unchanged in the current problem. Then it needs to be identified
as a "shared parameter", in which case, because the value of the
parameter is fixed with the current model, the frequency prior
needs to be adjusted in order to approximate the -2 log likeli-
hood function for the prior data when the parameter value is
regarded as being fixed in the prior model. (or when TNPRI is
being called in the Simulated Step, in order to use a conditional
prior distribution, given the parameter value is the fixed
value). A shared parameter may not actually be used in the cur-
rent problem, but the salient point is that with the current
problem, the interpretation of this parameter remains unchanged.
Alternatively, the parameter's interpretation may change in the
current problem. Then it needs to be identified as a "prior-spe-
cific" parameter, in which case if it is actually used in the
current model, its value will be the fixed value, but for the
purpose of applying the prior information, TNPRI will regard this
parameter as one specific to the prior model. The MODE argument
concerns this distinction.
0: All parameters with a nonfixed value in the prior problem but
a fixed value in the current problem are identified as being
prior-specific parameters. However, the final estimates of these
parameters are their fixed values.
1: All parameters with a nonfixed value in the prior problem but
a fixed value in the current problem are identified as being
prior-specific parameters. If the Estimation Step is imple-
mented, the final estimate for such a parameter is the same one
that would result from not fixing the value of the parameter in
the current problem and letting it be estimated, assuming that
the parameter is not at all used in the current model. This
value will be similar to the final estimate of the parameter in
the prior problem. (A difference from this prior estimate may
result, reflecting the fact that if there is a sequence of mod-
els, each a submodel of the one succeeding it, then the data used
to fit the last of the models may bear on a parameter peculiar to
the first model, if only slightly.) If indeed the parameter's
value were not fixed, but the parameter's estimate obtained along
with the estimates of the non-prior-specific parameters, then the
latter estimates and the minimum value of the objective function
would be unchanged, but the search for the parameter's estimate
would require additional computer time. With the value MODE=1,
in fact, the parameter's estimate is obtainable posthoc, after
the search, and this additional computer time is saved. The out-
put from the Covariance Step includes all the usual type of
information about the estimators of the prior-specific parameters
along with that about the estimators of the non-prior-specific
parameters. However, note that an output model specification
file will not contain any information about the estimates of
prior-specific parameters.
2: All parameters with a nonfixed value in the prior problem but
a fixed value in the current problem are identified as being
shared parameters (i.e. the frequency prior is adjusted). The
final estimates of these parameters are their fixed values.
ITYP
Relevant only if TNPRI is called during a Simulation Step. Val-
ues are:
0: The value of the UCP (unconstrained parameter) vector is
obtained from simple random sampling.
1: Within the given problem, TNPRI is to be called a specified
number (NSAM) of times to obtain this number of different values
of the UCP vector. These values are obtained by generating a
Latin sample of size NSAM from equiprobable partitions of an
ellipsoid in UCP space (hyper-ellipsoidal sampling), followed by
sampling a point "uniformly" from each partition. This scheme
may be used, for example, when the problem has NSAM subproblems,
in which case, TNPRI would be called NSAM times, once each time
during the problem when ICALL=4, and at each of these calls, a
different random value of the UCP vector will be produced.
2: Just as with value 1, but the NSAM values are obtained by gen-
erating a Latin sample of size NSAM from equiprobable partitions
of an ellipsoid in UCP space (hyper-ellipsoidal sampling), fol-
lowed by taking the "center point" of each partition.
In all three cases, a value of the UCP vector is transformed into
THETA-OMEGA-SIGMA space.
After each call to NWPRI, the simulated values for THETA, OMEGA
and SIGMA may be found in global variables and thus they are com-
municated directly to NONMEM. (See PRIOR_Simulation:_Parame-
ters).
PLEV
When TNPRI is being used at ICALL=0 or 1, but TNPRI will not be
used at ICALL=4 (i.e. during the Simulation Step), PLEV should be
set to 0. When it is being used at ICALL=2, PLEV should also be
set to 0. When TNPRI is being used at ICALL=0 or 1 and will also
be used at ICALL=4, or when it is being used at ICALL=4, then
PLEV must be set to a fraction strictly less than 1, e.g. 0.999. |
PLEV is double precision with NONMEM 7, and is single precision |
with NONMEM VI.
A UCP value will actually be obtained using a truncated multi-
variate normal distribution, i.e. from an ellipsoidal region R1
over which only a fraction of mass of the normal occurs. This
fraction is given by PLEV. Simple random sampling occurs in R1.
Latin sampled partitions are partitions of R1.
NSAM
Relevant only if TNPRI is called during a Simulation Step. Con-
sider two cases. a) Latin hyper-ellipsoid sampling is used with
ITYP=1, or b) simple random sampling along with the adjustment
for small sample correlation effect is used (see next input argu-
ment). In case a) NSAM should equal the exact total number of
different values of the parameter vector that must eventually be
produced over the entire NONMEM problem. In case b) NSAM should
be no less than this number.
ISS
Relevant only if TNPRI is called during a Simulation Step. A
value of the UCP vector is obtained by first sampling a value
from the standard multivariate normal distribution - called here
"the standard value" and then transforming this value to one from
the appropriate multivariate normal. The correlation matrix of
the standard normal is the identity matrix. When NSAM is small,
the estimated correlation matrix from the sampled standard values
might not be quite close to the identity matrix - this is here
called "the small sample correlation effect".
1: An adjustment is made for the small sample correlation effect,
by first transforming the NSAM standard values altogether into
new values which are very nearly standard multivariate normal
values and such that the sample correlation matrix of these new
values is exactly the identity matrix.
0: No adjustment is made for the small sample correlation effect.
IVAR
Relevant only if TNPRI is called during a Simulation Step. When
TNPRI simulates a parameter value, this value is that of an esti-
mate of the parameter from possible data under the prior model,
and this simulation is based on asymptotic statistical theory.
The partial derivatives comprising the R and S matrices referred
to below are taken with respect to the UCP (See covariance). The
possible values of IVAR are:
0: The variance-covariance matrix of the multivariate normal on
the UCP is taken to be two times the inverse R matrix obtained
from the prior problem. This could be appropriate if the esti-
mated asymptotic variance-covariance matrix from the prior prob-
lem is also based only on the R matrix.
1: The variance-covariance matrix of the multivariate normal on
the UCP is taken to be Rinv*S*Rinv matrix from the prior problem.
2: The variance-covariance matrix of the multivariate normal on
the UCP is taken to be S matrix from the prior problem. (NM75)
Briefly:
IVAR=0: Uses Rinv of a former problem.
IVAR=1: Uses Rinv*S*Rinv of a former problem
IVAR=2: Uses S of a former problem.
Output argument:
CNT Relevant only if TNPRI is called at ICALL=2. CNT is the penalty.
REFERENCES: Guide II Section D.2.5
Go to main index.
Created by nmhelp2html v. 1.0 written by Niclas Jonsson (Modified by AJB 5/2006,11/2007,10/2012)