+--------------------------------------------------------------------+
| |
| SIMETA |
| |
+--------------------------------------------------------------------+
MEANING: SIMETA subroutine
CONTEXT: NONMEM utility routine
USAGE:
USE SIZES, ONLY: DPSIZE,LVR
REAL(KIND=DPSIZE):: ETA(LVR)
CALL SIMETA (ETA)
DISCUSSION:
The NONMEM utility routine SIMETA can be called by PRED during the
simulation step, to obtain simulated eta values. It may be called
only when ICALL=4.
Output argument:
ETA An array into which SIMETA stores simulated eta values ETA(1),
ETA(2), ... The dimension of the array may be smaller than the
maximum, e.g., it may equal the number of etas in the problem.
Simulated eta values arise from a multivariate normal pseudo-random
distribution with mean 0 and variance-covariance as specified for
OMEGA. With different calls to SIMETA with different individual
records, new and different simulated eta values are obtained.
(With population data, an individual record has the same value of ID |
and may also be called a level-one "L1" record.) (See ID).
By default, with different calls to SIMETA with the same individual
record, the same simulated eta values are obtained - those obtained at
the first call with the record. (There is an advanced feature whereby
records are "repeated"
(See Repetition_Variables),
and when records of an individual record are being repeated, with dif-
ferent calls to SIMETA with the same individual record, the values
obtained are the last values stored in these variables when the record
was previously passed to PRED.)
If, though, the NEW option is used with the first random source on the
$SIMULATION record, then each time SIMETA is called (with the same or
different individual record), new and different values are obtained.
Thus, for example, when PRED is called with the first data record of
an individual record, PRED can in turn call SIMETA multiple times
until values are obtained such that, for example, ETA(2) is not larger
than 5 in absolute value; that is, values can be obtained from a trun-
cated distribution (see below). With any particular call to SIMETA,
the effect of the NEW option can, though, be overridden;
(See Simulation:_IETAOL_IEPSOL)
So that simple simulation can be easily implemented with abbreviated
code, values of etas are obtained by calls to SIMETA occurring in the
generated subroutine. When the data are population data, SIMETA is
called once per individual record by PRED (or PK if PREDPP is used).
(In the case of PK, the array of etas is stored in a common and is
available to the ERROR subroutine as well.) When the data are single-
subject data, SIMETA is called once at every call to PRED (once at
every call to ERROR if PREDPP is used).
These calls are implemented so that even if, initially, the Simulation
Step is not implemented, the NONMEM executable resulting from using an
abbreviated code for PRED (for PK or ERROR if PREDPP is used) can be
reused with a run implementing the Simulation Step.
EXAMPLES OF USAGE:
In this example, the value of ETA(2) used by PRED will be less than 5
in absolute value. For this code to have the desired effect, the
option NEW must be used in the $SIMULATION record.
IF (ICALL.EQ.4.AND.NEWIND.NE.2) THEN
DO WHILE (ABS(ETA(2)).GT.5)
CALL SIMETA (ETA)
ENDDO
ENDIF
Suppose there are two etas to be selected in this manner. Each one
needs its own CALL SIMETA loop, because each CALL SIMETA replaces all
the etas.
IF (ICALL.EQ.4.AND.NEWIND.NE.2) THEN
DO WHILE (ABS(ETA(2)).GT.5)
CALL SIMETA (ETA)
ENDDO
ETA2=ETA(2)
DO WHILE (ABS(ETA(1)).GT.0.52)
CALL SIMETA (ETA)
ENDDO
ETA1=ETA(1)
ENDIF
Another way this can be implemented is as follows:
IF (ICALL.EQ.4.AND.NEWIND.NE.2) THEN
DO WHILE(ABS(ETA(2)).GT.5.OR.ABS(ETA(1)).GT.0.52)
CALL SIMETA (ETA)
ENDDO
ETA2=ETA(2)
ETA1=ETA(1)
ENDIF
There is an analogous routine SIMEPS. (See simeps).
REFERENCES: Guide IV Section III.B.13, IV.I
REFERENCES: Guide V Section 12.4.8
REFERENCES: Guide VI Section III.E.2, IV.B.2
Go to main index.
Created by nmhelp2html v. 1.0 written by Niclas Jonsson (Modified by AJB 5/2006,11/2007,10/2012)