$simulat.ctl

___________________________________________________________________
| |
| $SIMULATION |
|_________________________________________________________________|

MEANING: Instructions for the NONMEM Simulation Step
CONTEXT: NM-TRAN Control Record

SAMPLE:
$SIMULATION (889215690) (2239177789 UNIFORM)

DISCUSSION:
Optional. Requests that the NONMEM Simulation Step be implemented.
May also be coded $SIMULATE or $SIML.

Usually, when the Simulation Step is implemented, the simulated obser-
vation is taken to be the quantity to which the Y variable (with NM-
TRAN abbreviated code) or F variable (with a user-supplied PRED or
ERROR routine) is set. This is the default behaviour. However, see
option NOPREDICTION below.

If a $ESTIM record appears in the problem specification, then unless
the LIKELIHOOD or -2LOGLIKELIHOOD option appears on the $ESTIM record,
etas (if any) are understood to be single-subject etas, except when
epsilons also appear, in which case the etas are understood to be
population etas. If a $ESTIM record does not appear, but a $SIMUL
record appears, then unless the NOPREDICTION option appears on the
$SIMUL record, etas are understood in the same way. When the NOPRED-
ICTION option is used, the etas are understood to be population etas.

In NM-TRAN abbreviated code, there can be a special block of code that
is implemented only during the simulation task (See ICALL, Simulation
Block). It is called a "simulation block".

OPTIONS:
The information coded within each set of parentheses defines the
attributes of a single random source. A source of random numbers is an
"infinite" stream of random numbers. Each pair of parentheses on the
record defines a separate source of random numbers, and the informa-
tion coded within the parentheses defines the attributes of the
source. The sources are ordered as they are defined on the $SIMUL
record. The numbers from a source are explicitly available to the
user via the NONMEM utility routine: RANDOM (See RANDOM). By default,
the first source is earmarked for the simulation of etas and epsilons,
and then the numbers from this source are not explicitly available to
the user.

seed1
Seed1 is the first seed for the random source, an integer between
0 and 21474836447. If this is not the first problem
specification in the control stream, then seed1 can be -1, indi-
cating that the random source is to be continued from the previ-
ous problem.

seed2
Seed2 is the second seed for the random source, an integer
between 0 and 21474836447. For use of a second seed, see NONMEM
Users Guide, Part IV.

NORMAL
The random numbers of the source are to be pseudo-normal with
mean 0 and variance 1 (unless the source is the first and used to
generate eta and epsilon realizations, in which case the
variance-covariance of these variables is that specified in the
$OMEGA and $SIGMA records). This is the default.

UNIFORM
The random numbers of the source are to be pseudo-uniform on the
interval [0,1].

NONPARAMETRIC
The random numbers from the first source defined with the NON-
PARAMETRIC attribute are used to generate realizations of random
vectors from a (multivariate) nonparametric distribution on eta,
obtained from the Nonparametric Step of an earlier problem. An
input MSF must also be present. It is understood that the etas
are to be simulated from the nonparametric distribution rather
than from the pseudo-normal distribution associated with the
first source. The NONPARAMETRIC attribute can only be used in
the definition of the second or subsequent source.

NEW
If the NEW option is used, the vector of eta's (epsilon's)
changes with each call to SIMETA (SIMEPS), rather than only at
the start of the next individual record (next level-two record).

ONLYSIMULATION
NONMEM is being asked to simulate data but not to evaluate an
objective function on these data. WRES values in tables and scat-
terplots will be 0. PRED-defined data items in tables and scat-
terplots will be computed using simulated etas and initial the-
tas.

$ESTIM, $COV and $NONP cannot be used with ONLYSIMULATION. Also,
see the PREDICTION and NOPREDICTION options.

SUBPROBLEMS=n
Requests that the entire NONMEM problem is to be repeated n times
in succession (including all NONMEM steps: simulation, estima-
tion, covariance, table, scatterplot). Each subproblem includes
the Simulation Step, but the random sources are simply continued
from subproblem to subproblem. If n=0 or n=1, there is only one
subproblem; this is the default. May also be coded SUBPROBS,
NSUBPROBLEMS, NSUBPROBS.

REQUESTFIRST
NONMEM sets a variable in read-only common ROCM12 informing PRED
whether or not PRED needs to compute first-partial derivatives
with respect to eta. Normally, during the Simulation Step, these
derivatives are not needed, either by NONMEM or by the user.
However, the user may want the first-partial eta derivatives of a
PRED-defined item and may want the ROCM12 variable to reflect
this. With the REQUESTFIRST option, the ROCM12 variable is set
so to inform PRED that the derivatives need to be computed. In
this case, if an abbreviated code is used to compute the PRED-
defined item, the item should not be computed within a simulation
block, because NM-TRAN does not provide derivatives for PRED-
defined items in a simulation block.

REQUESTSECOND
NONMEM sets a variable in read-only common ROCM12 informing PRED
whether or not PRED needs to compute second-partial derivatives
with respect to eta. Normally, during the Simulation Step, these
derivatives are not needed, either by NONMEM or by the user.
However, the user may want the second-partial eta derivatives of
a PRED-defined item and may want the ROCM12 variable to reflect
this. With the REQUESTFIRST option, the ROCM12 variable is set
so to inform PRED that the derivatives need to be computed. In
this case, if an abbreviated code is used to compute the PRED-
defined item, the item should not be computed within a simulation
block, because NM-TRAN does not provide derivatives for PRED-
defined items in a simulation block. REQUESTSECOND implies
REQUESTFIRST.

PREDICTION
Permitted only with ONLYSIM, and is the default.
With or without ONLYSIM, unless the NOPREDICTION is used, the
simulated observation is taken to be the quantity to which the Y
variable (with NM-TRAN abbreviated code) or F variable (with a
user-supplied PRED or ERROR routine) is set. In a simulation
block, the DV variable may be directly set to the simulated
observation, but the Y (or F) variable should also be set to this
observation. E.g., if a line of code DV=... is used in a simula-
tion block, be sure to follow this line with the additional line
Y=DV.

NOPREDICTION
Permitted only with ONLYSIM.
Indicates that the simulated observation will be taken to be the
value to which the DV variable is set. The code Y=... is permit-
ted inside or outside a simulation block, but if such code
appears in a simulation block, be sure to also include e.g. DV=Y.
Also, etas (if any) are understood to be population etas, even if
epsilons do not appear.

TRUE=INITIAL
The initial estimates given in the control stream are used as the
parameter values ("true values") in the simulation, except when a
model specification file is input. When a model specification
file is input, the initial estimates with the previous run are
used as the parameter values ("true values") in the simulation,
and the final estimates with the previous run are used as the
initial estimates in all tasks other than the simulation. The
UCP used with these other tasks are the same as with the previous
run. This is the default. May not be used with $MSFI in con-
junction with SUBPROBLEMS=n (n > 1).

TRUE=FINAL
An input model specification file must be used. The final esti-
mates with the previous run are used as the parameter values
("true values") in the simulation and as the initial estimates in
all tasks other than the simulation. The UCP used with these
other tasks are new, so that a UCP value of 0.1 now corresponds
to a final estimate from the previous run.

TRUE=PRIOR
The values stored in common NMPR16 by the PRIOR routine are used
as the true parameter values ("true values") in the simulation.

OMITTED
The Simulation Step is not implemented.

REFERENCES: Guide IV Section III.B.13, IV.I
REFERENCES: Guide V Section 12.4.8
REFERENCES: Guide VI Section III.C, III.E, IV.B, IV.G.1

Go to main index.

Created by nmhelp2html v. 1.0 written by Niclas Jonsson (Modified by AJB 5/2006,11/2007)