+--------------------------------------------------------------------+
| |
| DISPLAYED PRED-DEFINED ITEMS |
| |
+--------------------------------------------------------------------+
MEANING: Displayed values of PRED-Defined Items
CONTEXT: NONMEM output
DISCUSSION:
PRED-defined items can be displayed in tables and scatterplots. (This
includes PK-defined and ERROR-defined items.) These items are com-
puted and recomputed many times during a NONMEM run, with various val-
ues of theta and eta. It is important to know which values are used
in the computation of the items as displayed.
Consider this fragment of an NM-TRAN control stream:
$PK
CL=THETA(1)*EXP(ETA(1))
$TABLE CL ETA(1)
The values of ETA(1) and the PRED-defined item CL that are displayed
depend on which task specification records are present.
Task specification records THETA Displayed values
ETA(1) CL
----------------------------------------------------------------------------
none initial 0 typical
----------------------------------------------------------------------------
$EST (or $MSFI) METH=0 final 0 typical
----------------------------------------------------------------------------
$EST (or $MSFI) METH=1 or POSTHOC final conditional conditional
(CPE) (CPE)
----------------------------------------------------------------------------
$SIMULATION initial 0 typical
----------------------------------------------------------------------------
$SIMULATION ... ONLYSIM initial simulated* simulated
----------------------------------------------------------------------------
$NONPARAMETRIC ETAS final nonparametric nonparametric
(CNPE) (CNPE)
----------------------------------------------------------------------------
* Displayed etas are the simulated etas if the simulated etas are
stored in common NMPRD7. This is the case when NM-TRAN is used. If
they are not stored in NMPRD7, displayed etas are all 0.
Displayed values of PRED, RES, and WRES are always computed with typi-
cal values of parameters, except as noted below.
Displayed values of DV are simulated values when $SIMULATION is
present.
With NONMEM 7, Additional types of PRED, RES, and WRES values may be |
requested than the usual set available in NONMEM VI. They may be |
specified at any $TABLE command or $SCATTER command, as one would |
request PRED, RES, or WRES items. Such items are supplied internally |
by NONMEM, and in the case of L2 data, more accurately. An example of |
their use is in Example #4a, below. |
Every NONMEM output report contains the line: |
THE FOLLOWING LABELS ARE EQUIVALENT |
Subsequent lines show the relationship of such items for the current |
Estimation method. |
(See $table, $scatter). |
(See PRED,RES,WRES). |
See INTRODUCTION TO NONMEM 7, $TABLE: Additional Statistical Diagnos- |
tics, Associated Parameters, and Output Format
Suppose that marginal items appear. If this item is 1 or 2 on a given
record, the values of PRED and any PRED-defined displayed item D
(assuming D is not in the SAVE region (See comsav) associated with
this record) are determined as follows:
If the Simulation Step is implemented, and ONLYSIMULATION is speci-
fied, the PRED item is the simulation expectation of F, over the
simulated values of eta for all the individuals in the data set
(including those individuals with no observation records), and the D
item is the simulation expectation of the variable D.
If conditional estimates are obtained (e.g. with the use of the
POSTHOC option), the PRED item is the posterior expectation of F,
over the conditional estimates of eta for all individuals in the
data set (that have some observation records), and the D item is the
posterior expectation of the variable D.
Otherwise, the PRED and D items are the same as with a marginal item
of 0 (see description above).
Suppose that the raw-data items appear. If this is 1 on a given
record, the values of the DV, RES, and any PRED-defined displayed item
D (assuming D is in the SAVE region (See comsav) associated with this
record) are determined as follows:
The data record serves as a template record. The DV item appearing
in a table or scatterplot is the raw-data-average of the values of
DV in observation records matching the template record. The RES
item is the difference between the PRED item and this average. A
PRED-defined item D is the average of the values of D obtained with
observation records matching the template.
(See mrg, raw, template).
Several examples will illustrate techniques for displaying (subject-
specific) conditional values, (non-subject-specific) typical values,
and simulated values.
#1 Display typical and conditional values using different variables:
$PK
...
TVCL=THETA(1)
CL=TVCL*EXP(ETA(1))
$ESTIM ... POSTHOC ...
$TABLE TVCL CL
TVCL is a typical value by definition. CL is a conditional value.
#2 Display typical and conditional values of the same variable:
$PK
...
CL=THETA(1)*EXP(ETA(1))
IF (COMACT.EQ.1) TVCL=CL
$ESTIM ... POSTHOC ...
$TABLE TVCL CL
TVCL is a SAVE variable because it is defined in a copying block.
During the copying pass with COMACT=1, it is set to the typical value
of CL, because when COMACT=1, etas are 0. Were the values of TVCL not
stored in the SAVE region, then during the copying pass to obtain val-
ues for tables and with COMACT=2, TVCL would retain its value set with
the previous data record.
The first column of the table is labelled TVCL and contains the typi-
cal value of CL, and the second column contains the conditional value.
#3 Display typical and conditional values of the prediction, and the
individual residual and weighted residual values:
$ERROR
IPRED=F
IRES=DV-IPRED
IWRES=IRES/IPRED
Y=F+EPS(1)
$ESTIM ... POSTHOC ...
$TABLE IPRED IRES IWRES
The IPRED column contains the conditional value of F ("individual pre-
diction"). (F is not a left-hand quantity and cannot be specified in
a $TABLE or $SCATTERPLOT record.) The PRED column contains the typi-
cal value. The IRES column contains the "individual residual". The
IWRES column contains a value which is proportional to (but not equal
to) the "individual weighted residual".
If predicted values of F may be zero, then division by zero can be
avoided by code such as the following.
$ERROR
IPRED=F
IRES=DV-IPRED
DEL=0
IF (IPRED.EQ.0) DEL=1
IWRES=(1-DEL)*IRES/(IPRED+DEL)
Y=F+EPS(1)
#4 Display intra-individual weighted residual:
This uses the constant CV intraindividual error model, and allows one
to display the weighted intra-individual residual that is used during
Estimation when the FOCE method without interaction is used.
$ERROR
Y=F+F*EPS(1)
IPRED=F
IF (COMACT.EQ.1) FT=F
IF (FT.NE.0) WR=(DV-IPRED)/FT/SQRT(SIGMA(1,1)) |
IF (IPRED.NE.0) WR2=(DV-IPRED)/IPRED/SQRT(SIGMA(1,1)) |
$ESTIM METHOD=COND
$TABLE FT IPRED WR WR2
IPRED is the conditional estimate of F.
FT is a SAVE variable because it is defined in a copying block. Dur-
ing the copying pass with COMACT=1, it is set to the typical value of
F, because when COMACT=1, etas are 0. Were the values of FT not
stored in the SAVE region, then during the copying pass to obtain val-
ues for tables and with COMACT=2, FT would retain its value set with
the previous data record.
WR is the weighted intraindividual residual with no eta-eps interac- |
tion. It is defined in a conditional assignment since it is possible |
that the typical value of F is zero with some non-observation record. |
(With previous versions of the help guide the SIGMA term was omitted |
and the WR was proportional to the weighted intraindividual residual.) |
It is a no-interaction residual because the denominator term, the |
residual standard deviation FT*SQRT(SIGMA(1,1)), represents the |
epsilon error, and uses the predicted value (FT) evaluated with eta=0, |
that is, eta does not interact with the epsilon error. WR2 is the |
conditional intra-individual weighted residual with eta-eps interac- |
tion. It is an eta-eps interaction residual because the denominator |
term, the residual standard deviation IPRED*SQRT(SIGMA(1,1)), repre- |
sents the epsilon error, and uses the predicted value (IPRED) evalu- |
ated with a non-zero eta, that is, eta interacts with the epsilon |
error. |
#4a Display intra-individual weighted residual using reserved vari- |
ables |
With NONMEM 7, It is possible to obtain the same table more easily, as |
follows, using the reserved residual variables CIWRES (=WR) and |
CIWRESI(=WR2) : |
$ERROR |
Y=F+F*EPS(1) |
$ESTIM METHOD=COND |
$TABLE IPRD CIPRED CIWRES CIWRESI |
#5 Display simulated values:
$PK
...
CL=THETA(1)*EXP(ETA(1))
...
$SIMULATION (seed) ONLYSIM
$TABLE ETA(1) CL
ETA(1) and CL are simulated values.
#6 Display simulated and estimated values:
$INPUT .... CLSM E1SM ...
$PK
...
CL=THETA(1)*EXP(ETA(1))
IF (ICALL.EQ.4) THEN
CLSM=CL
E1SM=ETA(1)
ENDIF
$SIMULATION (seed)
$ESTIM
$TABLE CLSM E1SM CL ETA(1)
Modification of the data record during the simulation pass is the only
way to save the simulated values in the absence of ONLYSIM. Column 1
and 2 of the table are the simulated values. Column 3 and 4 are the
typical values.
#7 Display conditional values of a variable in each of two mixture
subpopulations:
$PK
...
IF (MIXNUM.EQ.1) CL= ...
IF (MIXNUM.EQ.2) CL= ...
IF (COMACT.EQ.2) THEN
IF (MIXNUM.EQ.1) CL1=CL
IF (MIXNUM.EQ.2) CL2=CL
ENDIF
$ESTIM ... POSTHOC ...
$TABLE CL1 CL2
CL1 (and CL2) is a SAVE variable because it is defined in a copying
block. Were the values for CL1 not stored in the SAVE region, during
the copying pass to obtain values for tables and with MIXNUM=2, CL1
would retain its value set with the previous data record.
#8 Display conditional values of a variable in the subpopulation into
which the individual is classified:
$PK
...
IF (MIXNUM.EQ.1) CL= ...
IF (MIXNUM.EQ.2) CL= ...
IF (COMACT.EQ.2.AND.MIXNUM.EQ.MIXEST) CLE=CL
$ESTIM ... POSTHOC ...
$TABLE CLE
CLE is a SAVE variable because it is defined in a copying block. Were
the values for CLE not stored in the SAVE region, during the copying
pass to obtain values for tables and with MIXNUM>MIXEST, CLE would
retain its value set with the previous data record.
REFERENCES: Guide IV Section III.B.7, IV.E.2
REFERENCES: Guide VI Section III.J, IV.E
REFERENCES: Guide Section 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)