$CHAIN

The optional record specifies initial estimates for an entire problem.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15


   $CHAIN  [FILE=filename]
           [FORMAT=s] [ORDER=xxxf]
           [NOTITLE=[0|1]] [NOLABEL=[0|1]]
           [ISAMPLE=n][NSAMPLE=n]
           [SEED=n]
           [CLOCKSEED=[0|1]]
           [SELECT=n]
           [RANMETHOD=[n|S|m] ]
           [CTYPE=[0|1|2|3|4]]
           [DF=n]
           [DFS=n]
           [IACCEPT=x]
           [TBLN=n]
  ;# Example
   $CHAIN FILE=example1_previous.txt NSAMPLE=0 ISAMPLE=-1000000000

Initial parameters set by $CHAIN are persistant throughout the entire problem. This is different from $EST METHOD=CHAIN that is for the Estimation Step; the Simulation Step is unaffected and still uses the initial values from an MSF file or $THETA, $OMEGA, and $SIGMA records.

If ISAMPLE=0, then the initial values are not set to any of the randomly generated samples, but will just be what was listed in $THETA and $OMEGA of the control stream file.

Sample distributions

`THETA`

CTYPE=0 (default): use a uniform distribution for THETA sampling, with the bounds from the $THETA record. If bounds not specified, then the interval is $$ [(1-\text{IACCEPT})\theta, (1+\text{IACCEPT})\theta] $$
CTYPE=1: ignore the bounds from $THETA and sample THETAs uniformly using the IACCEPT.
CTYPE=2: use a multivariate normal distribution with the initial $THETA as the mean. When $PRIOR is used and NTHP>0, the covariance matrix is from the second set of $OMEGA (equivalanetly $THETAPV); otherwise, the covariance matrix is from $OMEGA. The second scenario requires that the THETA be MU modeled: those that are not MU modeled follow the uniform distribution as if CTYPE=0.

`SIGMA`

See DFS.

`OMEGA`

OMEGA samples follow a Wishart distribution with covariance from $OMEGA, and Degrees of Freedom DF. DF=0 makes the dimension of the entire OMEGA matrix is used as the DoF. In NM73+, setting DF>1E6 fixes OMEGA elements at their initial values.

Options

$CHAIN shares the following options with $EST METHOD=CHAIN: FILE, NSAMPLE, ISAMPLE, ISAMPEND, SEED, CLOCKSEED, RANMETHOD, FORMAT, ORDER, CTYPE, DF, DFS, IACCEPT, NOLABEL, and NOTITLE.

SEED and RANMETHOD in $CHAIN do not propagate to $EST METHOD=CHAIN or any other $EST record.
ISAMPEND (NM73): different from $EST METHOD=CHAIN, with $CHAIN NONMEM uses discrete uniform distribution to sample in ISAMPLE...ISAMPEND. This is useful for the $SIML record:
1 2 3 4

$CHAIN FILE=test2.chn ISAMPLE=3 ISAMPEND=10 NSAMPLE=10 SEED=6234 $SIML (112345) (334567 NORMAL) SUBP=4 $EST METHOD=IMP INTERACTION NITER=40 PRINT=1 NOABORT SIGL=4 CTYPE=3 CITER=10
The example above shows that there are four (SUBP=4) subproblems. For each subproblem, NONMEM samples uniformly from sample 3 (ISAMPLE=3) to sample 10 (ISAMPEND=10). These eight samples are among the ten (NSAMPLE=10) randomly generated sets of THETA, OMEGA, and SIGMA. The parameter set is than used for simulation, followed by an estimation that fits the simulated data. This process is repeated for four times (SUBP=4).
NSAMPLE=0 requests reading random samples from FILE, generated for example from a previous MCMC run:
1 2

$CHAIN FILE=example1.chn ISAMPLE=0 ISAMPEND=10000 NSAMPLE=0 SEED=6234 $SIML (112345) (334567 NORMAL) SUBP=100
The "example1.chn" file above in fact the raw output file "example1.txt" from the Bayesian estimation in "examples/example1". In general the uniform sampling is performed among ISAMPLE...ISAMPEND, with cutoff of the actual number of samples in the file. Therefore one can use a large ISAMPEND as in the above example.
One can use ISAMPLE=-1000000000 to pick up the final estimates from the raw output:
1

$CHAIN FILE=example1_previous.txt NSAMPLE=0 ISAMPLE=-1000000000 TBLN=4
In NM75+, one may also select the table number TBLN, as raw output files can contain multiples tables of results. If not specified, the first matching ISAMPLE number is selected. This provides an approach to import values from a raw output.
$CHAIN ... ISAMPEND overrides $SIML TRUE=PRIOR.