___________________________________________________________________
 |                                                                 |
 |                                SIMETA                           |
 |_________________________________________________________________|

 MEANING: SIMETA subroutine
 CONTEXT: NONMEM utility routine

 USAGE:
 (If double precision is to be used):
 DOUBLE PRECISION ETA(LVR)
 (If single precision is to be used):
 REAL ETA(LVR)
  ...
 CALL SIMETA (ETA)

 The value of LVR must  be  the  same  as  that  found  in  file  SIZES
 (See sizes).

 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.  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 nmpr10), and when records of an individual
 record are being repeated, with different calls  to  SIMETA  with  the
 same individual record, the values obtained are the last values stored
 in nmprd7 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  nmpr11.
 So  that  simple simulation can be easily implemented with abbreviated
 code, values of etas are obtained by calls to SIMETA occurring in  the
 generated  or NM-TRAN Library 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

 (See sizes).

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)