Running_QRPEM_in_command_line

Running QRPEM in command line mode

The numerical engine code for the QRPEM engine is 1, so a typical command line invocation of QRPEM with model file test.mdl, column mapping file cols1.txt, data file data1.txt, and a maximum iteration limit of 200 takes the form:

   runnlme.bat 1 200 test.mdl cols1.txt data1.txt

The output files for QRPEM are the same as for the other engines.

QRPEM control flags

In addition to the standard engine controls that can be provided in the file nlmeflags.asc discussed previously (see “The lognlmeflags.asc control file”) and which generally apply to all engines, there are some QRPEM-specific controls that apply only to the QRPEM engine and that are passed in a simple text file qrpemflags.asc.

Note: In UI mode, these controls are set in the Run Options tab.

As with nlmeflags.asc, if the qrpemflags.asc file is omitted, the default values of the various QRPEM controls will be used. However, to override any of the QRPEM default control values, the qrpemflags.asc file must be provided in the current active directory (typically the directory containing the model, mapping, and data files). A sample qrpemflags.asc file containing default values of the controls is shown below and is also provided in …\Examples\NLME\Command Line.

300  !Nsamp        number of eta samples per subject
0    !impsamptype  type of importance sampling
0    !impmapflag   0=no MAP assist after first iteration, 
                   1=MAP step on every iteration
0    !iflagmcpem   0=QRPEM sampling, 1=MCPEM sampling
1    !iflagscramble   0=none, 1=Owen, 2=Faure-Tezuka
10   !NSIR         sample size for estimating fixed effects 
                   not associated with random effects 
       0.1d0  !acceptance ratio 
0    !irunall      if irunall=1, all iterations will be run, 
                   regardless of convergence behavior
0    !Nburn        number of burn in iterations
0    !ifreezeOmega freeze Omega during burn-ins flag (0=no, 1=yes)
0    !ipostrestart posterior restart flag: 0=no, 
                   1=use posteriors from previous run if available
! end qrpemflags.asc

QRPEM Control Flags

acceptance ratio: A real valued (default=0.1) parameter that controls the ratio g of the covariance matrix of the importance sampling distribution to the estimated covariance matrix of the underlying posterior distribution.

The formula used is:
acceptance_ratio = g^–2/d

where d is the number of random effects. To insure an adequate sampling in the tails of the target posterior distribution, a g > 1, corresponding to acceptance ratio < 1, is desired. Decreasing the acceptance ratio increases g and widens the tails of the importance sampling distribution. However, if this is taken too far, the sampling becomes very inefficient since most sample points will lie in the tails far from the highest likelihood region and hence will be uninformative. Note that as an alternative to decreasing acceptance ratio, one of the fatter tail distributions MVL or MVT can be used.

iflagmcpem: A binary 0/1 flag.

Default=0 or off.

If set to 1, QR sampling is turned off and replaced by Monte Carlo random sampling. This may be of interest for pedagogical purposes or if the most direct comparison possible is desired with other MCPEM algorithms such as those found in NONMEM 7 or S-ADAPT. However for production runs, using the default setting MCPEM=0 is strongly recommended to get the speed and accuracy advantages of QR sampling.

iflagscramble: A numeric selector that determines whether and what type of ‘scrambling’ is used.

0: No scrambling.

1: Owen scrambling, the default.

2: Faure-Tezuka scrambling.

Scrambling is a technique that de-correlates the components of the quasi-random sequence, making it look more random, without affecting the basic low discrepancy property that improves the accuracy of QR relative to random sampling for numeric integration. In some cases, use of scrambling can further improve the numerical accuracy of the integrals relative to a basic non-scrambled QR sequence.

ifreezeomega: Modifies the meaning of Nburn. If ifreezeomega=1, then Omega is frozen during the burn in iterations.

impsamptype: Specifies the importance sampling type:

= –2: Use a defensive Gaussian mixture with 2 components.

= –3: Use a defensive Gaussian mixture with 3 components.

=0: Use a standard Gaussian distribution (no mixture), also referred to as multivariate normal (MVN).

=1: Use a multivariate Laplace distribution (MVL). The MVL distribution has fatter tails than the corresponding normal distribution with the same mean and covariance matrix.

=2: Use a direct sampling, which means to sample directly from the N(0,Omega) population distribution, and not use any importance sampling at all.

> 2: Use a multivariate T (MVT) with impsamptype degrees of freedom. A value within the general range of four to 10 is recommended if an MVT distribution is desired. Any values larger than this are not significantly different than the MVN distribution and will be inefficient relative to simply using MVN. The T distribution has fatter tails that decay more slowly than the corresponding MVN distribution. The MVT decay rate is governed by the degrees of freedom: lower values correspond to slower decay and fatter tails.

The rationale for using MVL or MVT is to increase the sampling frequency from the target posterior distribution tails in case that distribution has more slowly decaying tails than that of a multivariate normal distribution. An alternative to using MVL or MVT to accomplish this is to use a lower value of acceptance ratio, as discussed below.

ipostrestart: The posterior restart flag.

=0: Restart is not used.

=1: The final posterior means and covariance matrices from the immediately preceding run are used to initiate the current run.

irunall: A binary (0 or 1) flag that determines how many iterations will be run.

1: All iterations that are requested on the command line to be run.

0: (Default) Iterations will be run until either a) convergence is achieved, or b) the maximum number of iterations is hit.

Thus setting irunall in effect turns off application of the convergence criterion.

Nburn: An integer that specifies how many burn in or preconditioning iterations are performed before actual optimization steps are attempted.

During these burn in iterations, only internal parameter values related to the estimated means and covariances of the posteriors are changed, but no changes are made to fixed or random effect parameter estimates. Generally, burn in iterations are only necessary when evaluating the log likelihood at the initial estimate (this is done by specifying zero iterations in the command line iteration limit), in which case about 15 burn in iterations are usually adequate. During the burn in process, the reported log likelihood value at the starting point will converge to an accurate estimate of the actual log likelihood at that point. The default setting is zero burn in iterations.

Nsamp: The number of samples used to evaluate the posterior mean and covariance integrals for each subject.

Increasing this value will improve the accuracy of the integrals and the likelihood evaluation, and generally will result in better (closer to the true maximum likelihood values) parameter estimates, but will also increase execution time. The maximum permissible value is 30000.

NSIR: An integer that determines the number of Sampling-Importance-Resampling points/per subject to include in the nonlinear log likelihood optimization.

This optimization is used to estimate fixed effects that appear in nonlinear covariate models, residual error models, and any instance of a fixed effect that is not paired with a random effect in a structural parameter definition. Increasing # SIR samples will improve the accuracy of these estimates but at higher computational cost. The total number of samples is the product of # SIR samples and the number of subjects. Thus with 100 subjects and the default value of # SIR samples=10, a total of 1000 samples is used, which is usually more than adequate. Normally # SIR samples should only be increased if the number of subjects is small. The maximum value of # SIR samples is ISAMPLE, the total number of sample points per subject.