Input_files

model file: mandatory command line argument 4

colmap file: mandatory command line argument 5

data file: mandatory command line argument 6

nlmeflags.asc: optional control file

logrestart.asc: optional restart file

The three mandatory input files are always designated in the command line.

An optional fourth control input file called nlmeflags.asc is used to set certain environmental flags and tolerances to values other than the default values. If this file is not present in the command line arguments, then the environmental flags and tolerances are set to their default values. The file is created with every modeling run.

The format and default values of the nlmeflags.asc file are listed below. Every successful run of the NLME engine creates a lognlmeflags.asc file which contains flags and values that can be copied to the nlmeflags.asc file.

Copy the text from lognlmeflags.asc to nlmeflags.asc and change the applicable values in order to create and use nlmeflags.asc file in a modeling run.

The optional fifth command line argument input file is called logrestart.asc. It is used to designate an initial starting solution other than that specified in the model file. Every successful run of the NLME engine creates a logrestart.asc file which can then be used to initialize later runs.

The flag for controlling whether or not to use logrestart.asc is in the !iflagrestart line in nlmeflags.asc.

Example usage for the command line arguments:

RunNLME 5 500 lyon04.mdl COLS04.TXT EMAX02.csv nlmeflags.asc logrestart.asc

The lognlmeflags.asc control file

The standard lognlmeflags.asc control file consists of 11 lines with standard default values specified as entries. The following lines are typical contents of a lognlmeflags.asc file:

0  !iflagnp (0=do not run, otherwise # of nonparametric generations)
0  !iflagrestart (0=no, 1=start from solution in logrestart.asc)
1  !norderAGQ
1  !iflagfocehess (1=foce, 0=Laplacian numerical Hessian)
1  !iflagverbose (verbose mode is always used)
0  !iflagstderr (0=none, 1=central diff, 2=forward diff)
      1 -1   !METHODblup, NDIGITblup (expert usage, do not change)
      1  7   !METHODlagl, NDIGITlagl (expert usage, do not change)
    0.100E-02 !tolmodlinz (step size for model linearization)
1  !iflagIEXP (1=secant, 0=hessian)
    0.100E-01 !tolstderr (step size for standard error computation)
0  !nrep_pcwres (0=do not run, otherwise # of replicates)
0  !npresample (not currently used)
0  !niter_mapnp (0=do not run, otherwise # of MAP_NP iterations)

Note: If the nlmeflags.asc control file is not used then the default values are used. The file lognlmeflags.asc logs which values were used in a modeling run.

Control Flags

!iflagfocehess: Controls how the Hessian matrix is approximated.

=1: FOCE L-B approximation to compute the approximation to the Hessian matrix of the joint log likelihood function for each individual.

=0: Hessian matrix is approximated by numerical differentiation.

!iflagIEXP: Specifies whether calculation of the likelihood function is too expensive or not to calculate.

=0: The overall quasi-Newton optimization step assumes that the likelihood function is not too “expensive” to evaluate and a numerical Hessian matrix is used for the Newton step.

=1: Overall likelihood function is assumed to be too “expensive” to evaluate, which is almost always true for NLME estimation problems, and a secant approximation is used. It is suggested that iflagIEXP=1 always be used.

!iflagnp: Controls whether and how intensively to run a nonparametric analysis after the initial parametric analysis is run.

= 0: No nonparametric analysis is run.

>0: Designates the number of generations to run in the evolutionary nonparametric algorithm.

=1: Optimal probabilities on support points placed at the parametric post hoc estimates are computed.

>1: Support point positions are also optimized (can be computationally intensive). The output of probabilities and support points is sent to the file nparsupport.asc.

!iflagrestart: Specifies the source of the initial solution.

=0: Initial solution consists of the starting values in the model file.

=1: Initial solution is read from the logrestart.asc file, which is created during a previous run of the same model.

!iflagstderr: Controls the standard error computation.

=0: No standard error computation is attempted.

=1: A standard error computation with central differences for the required second derivatives of the log likelihood is attempted. This is much more computationally intensive but more accurate than forward differences.

=2: Forward differences are used.

>0: The relative step size to be used is specified in !tolstderr.

!iflagverbose: This value is always set to 1, so verbose mode always used.

!METHODblup: Expert usage only.

This flag specifies the optimization method (1=line search, 2=dogleg, 3= Levenberg-like trust region) to be used in the OPTIF9 routine for optimization of the “blups,” which are post hoc estimates or modes of the joint likelihood function for each individual. It is best practice to not deviate from the default.

!METHODlagl: Similar to !METHODblup, but applicable to the OPTIF9 optimization of overall likelihood function in engine five. It is suggested that the default be used.

NDIGITblup: Expert usage only.

This is an input of the estimate of the available accuracy of the OPTIF9 blup objective function in terms of decimal places. It is best practice to not deviate from the default.

NDIGITlagl: Similar to NDIGITblup, but applicable to the OPTIF9 optimization of overall likelihood function in engine five. It is best practice to not deviate from the default.

!niter_mapnp: Controls whether or not the MAP_NP procedure for improving initial fixed effect guesses is used.

If niter_mapnp=0, this option is not used. Otherwise, it is used for niter_mapnp iterations (a reasonable value to use is niter_mapnp=3).

!norderAGQ: Only applicable to engine five, and is ignored for other engines.

This flag designates the number of adaptive Gaussian quadrature (AGQ) points along each random effects dimension. The maximum value=40, but note that the total number of quadrature points is norderAGQ^(number of random effects), so it is best practice to use a small integer, unless the number of random effects is one.

=1: Corresponds to the Laplacian approximation.

>1: Adaptive Gaussian quadrature is used.

Exceptions include:

If norderAGQ=1 and iflaghess=1, then the FOCE ELS (Extended Least Squares) objective function is used, which is similar to NONMEM FOCE.

If norderAGQ=1 and iflaghess=0, then the Laplacian objective function is used, which is similar to NONMEM Laplacian objective function.

If norderAGQ>1 and iflaghess=1, then an adaptive Gaussian quadrature is created with a Gaussian kernel defined by the FOCE approximation.

If norderAGQ>1 and iflaghess=0, then an adaptive Gaussian quadrature is created with a Gaussian kernel defined by a numerical differentiation Hessian approximation.

!npresample: Not currently used.

!nrep_pcwres: Controls whether or not the simulation based PCWRES statistic is computed in the residuals table. If nrep_pcwres=0, the statistic is not computed. Otherwise, it is computed using nrep_pcwres simulation replicates (maximum of 1000).

!tolmodlinz: Relative step size to use in numerical differentiation of the model function for FOCE L-B linearization.

!tolstderr: Relative step size to use in differentiation of log likelihood function for computation of standard errors.