wfncs

Control Streams

Last Updated: 5 October 2015

Parameter Names

Any NM-TRAN control stream can be used with WFN. However, certain conventions are recommended to increase the usefulness of WFN. The most obvious is to format $THETA, $OMEGA and $SIGMA records with one parameter value per line and to add a comment on that line containing a meaningful parameter name. The parameter names are used to label the columns in the run summary.

Parameter names are taken from the first non-numeric word after the comment delimiter ";" e.g. the following examples all produce the parameter name "POP_E0" for THETA(1). Unlike a standard control stream there is not a 6 character limit on the length of these names when they are used on the right hand side of an expression. Note that names longer than 8 characters will lose the column alignment of parameters with values in the run summary. Variable names on the left hand side of expressions must follow standard NM-TRAN control stream format rules.

$THETA (0,150.,) ; POP_E0
$THETA (0,150.,) ; 1 POP_E0
$THETA (0,150.,) ; POP_E0 1
$THETA (0,150.,) ; pop_e0
$THETA (0,150.,) ; POP_E0 L/min

Parameter names followed immediately by "(" or "{" or "[" or ";" are recognized e.g. all of the following will find "POP_E0" as the parameter name.

$THETA (0,150 ) ;POP_E0(1)
$THETA (0,150 ) ;POP_E0{1}
$THETA (0,150 ) ;POP_E0[1]
$THETA (0,150 ) ;POP_E0;1

When $OMEGA BLOCKs are used each row of off-diagonal and diagonal elements should be on one line with a following comment and parameter name for the diagonal element.

$OMEGA BLOCK (2)
0.5 ; PPV_E0
0.1 0.5 ; PPV_EMAX

If the SAME option is used then a parameter name can be specified by inserting an $OMEGA BLOCK record with subsequent records with a ";;" delimiter as the first two characters on the line. This convention is only required when using an extended control stream.

$OMEGA BLOCK (2)
0.5 ; BOV_E0
0.1 0.5 ; BOV_EMAX
$OMEGA BLOCK (2)SAME
;; BOV_E02
;; BOV_EMAX2

File Names

nmgo creates a run-directory as a sub-directory in the directory nmgo is invoked from. If the control stream $DATA record refers to a filename without a path then the file name will have "..\" prepended to it so that NM-TRAN can find the data file which is presumably located in the same directory as the original control stream. If the $DATA file name has a path or drive letter attached to it then no changes are made to the data file specification.

Control streams (standard or extended) will have the MSFO and (first) TABLE FILE name changed so that they reflect the runname with the extension .msf or .fit. TABLE FILE names which match /^..tab/ are not changed for compatability with xpose (Jonsson & Karlsson 1997) conventions e.g. the MSFO file for the control stream defined in theopd2.ctl would be renamed theopd2.msf and the table file would be renamed theopd2.fit.

Extended Control Stream

WFN supports an extended form of NM-TRAN control stream. The extended control stream is not case sensitive (but preserves case of filenames), allows embedded tab characters and does not require explicit THETA, ETA or ERR references in the model code. Standard control stream records may be freely mixed with extended control stream records.

Standard Control Stream

Theopd.ctl is an example of a standard NM-TRAN control stream which uses an Emax pharmacodynamic model to describe the relationship between theophylline concentration and peak expiratory flow rate (PEFR) in patients with severe airways obstruction (Holford et al. 1993a).

$PROB theophylline pharmacodynamics standard control stream
$DATA theopd.dat IGNORE #
$INPUT ID TIME THEO AGE WT SEX RACE DIAG DV
$ESTIM METHOD=ZERO POSTHOC
MSFO=theopd.msf
$COV
$THETA

(0,150.,) ; POP_E0 1
(0,200.,) ; POP_EMAX 2
(.001,10,) ; POP_C50 3
$OMEGA

0.5 ; PPV_E0 1
0.5 ; PPV_EMAX 2
0.5 ; PPV_C50 3
$SIGMA

100 ;RUV_SD 1

$PRED
E0=THETA(1)*EXP(ETA(1))
EMAX=THETA(2)*EXP(ETA(2))
C50=THETA(3)*EXP(ETA(3))
Y = E0 + EMAX*THEO/(THEO+C50) + ERR(1)
$TABLE ID TIME THEO AGE WT SEX RACE DIAG
E0 EMAX C50 Y
NOPRINT ONEHEADER FILE=theopd.fit

Extended Control Stream

The following is an example of an extended control stream (theopd2.ctl) which implements the same code as the standard control stream. Parameter names are used in the model records to identify where THETA, ETA and ERR references are required when the extended control stream is translated into the standard control stream for NM-TRAN. Use of the extended control stream means it is no longer necessary to count each of the $THETA, $OMEGA and $SIGMA records and tediously ensure they match with the THETA, ETA and ERR subscripts in the model.

I have used the prefix "pop" for population parameters, "eta" for population parameter random effects and "err" for residual unknown random effects. This is a personal convention. You may choose any parameter names you wish to identify THETA, ETA and ERR in the control stream.

$PROB theophylline pharmacodynamics extended control stream
$DATA theopd.dat IGNORE #
$INPUT ID TIME THEO AGE WT SEX RACE DIAG DV
$ESTIM METHOD=ZERO POSTHOC
MSFO=theopd.msf
$COV
$THETA

(0,150.,) ; POP_E0 1
(0,200.,) ; POP_EMAX 2
(.001,10,) ;POP_C50 3
$OMEGA

0.5 ; PPV_E0 1
0.5 ; PPV_EMAX 2
0.5 ; PPV_C50 3
$SIGMA

100 ;RUV_SD 1

$PRED
E0=POP_E0*EXP(PPV_E0)
EMAX=POP_EMAX*EXP(PPV_EMAX)
EC50=POP_C50*EXP(PPV_C50)
Y = E0 + EMAX*THEO/(THEO+EC50) + RUV_SD
$TABLE ID TIME THEO AGE WT SEX RACE DIAG
E0 EMAX C50 Y
NOPRINT ONEHEADER FILE=theopd.fit

A special convention is used when parameter names occur on the left hand side of an expression. Once a parameter name has appeared on the left hand side no further substitutions are made when that parameter name appears in any following right hand side expressions. A model record in this context is any $PRED, $PK, $ERROR, $DES, $AES record. After translation the extended control stream example will be identical to the standard control stream example.