EsN - Extended Control Stream

Overview

Extended control streams are originally defined in Nick Holford's Wings for NONMEM application. Emacs for NONMEM allows extended control streams to be used regardless of the platform you are using. There are a few differences in implementation, though. Much of this description was shamelessly lifted (with permission) from the Wings for NONMEM extended control stream definitions.

Key Definitions

Parameter Names

Any control stream can be used with Emacs Speaks NONMEM. However, certain conventions can be used to interface with Wings for NONMEM, and allow renumbering of THETA, OMEGA and SIGMA variables within Emacs Speaks NONMEM. One of these conventions is formatting $THETA, $OMEGA and $SIGMA records with one parameter value per line and adding a comment on that line that contains a meaningful parameter name labels the parameter.

Parameter names are taken from the first non-numeric word after the comment delimiter ";" e.g. the following examples all produce the parameter name "POPE0" 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.

$THETA (0,150.,) ; POPE0
$THETA (0,150.,) ; 1 POPE0
$THETA (0,150.,) ; POPE0 1
$THETA (0,150.,) ; pope0
$THETA (0,150.,) ; POPE0 L/min

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

$THETA (0,150 ) ;POPE0(1)
$THETA (0,150 ) ;POPE0{1}
$THETA (0,150 ) ;POPE0[1]
$THETA (0,150 ) ;POPE0;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 ; ETAE0
0.1 0.5 ; ETAEMAX

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 ; ETAE0
0.1 0.5 ; ETAEMAX
$OMEGA BLOCK (2)SAME
;; ETAE02
;; ETAEMAX2

Extended Control Stream

Wings for NONMEM and Emacs Speaks NONMEM supports an extended form of NM-TRAN control stream. The extended control stream is not case sensitive (but preserves case of filenames, comments, exclusion characters, etc.), allows embedded tab characters and does not require explicit THETA, ETA or ERR/EPS references in the model code. Standard control stream records may be freely mixed with extended control stream records when submiting to Wings for NONMEM. Otherwise, Emacs Speaks NONMEM chooses one model to maintain.

Example: 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 GEND RACE DIAG PEFR=DV
$ESTIM PRINT=1 POSTHOC
MSFO=theopd.msf
$COV
$THETA (0,150.,) ;popE0 1
$THETA (0,200.,) ;popEMAX 2
$THETA (.001,10,) ;popEC50 3
$OMEGA 0.5 ;etaE0 1
$OMEGA 0.5 ;etaEMAX 2
$OMEGA 0.5 ;etaEC50 3
$SIGMA 100 ;errSD 1
$PRED
E0=THETA(1)*EXP(ETA(1))
EMAX=THETA(2)*EXP(ETA(2))
EC50=THETA(3)*EXP(ETA(3))
Y = E0 + EMAX*THEO/(THEO+EC50) + ERR(1)
$TABLE ID TIME THEO AGE WT GEND RACE DIAG
E0 EMAX EC50 Y
NOPRINT ONEHEADER FILE=theopd.fit

Example: 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" or "eps" for residual unknown random effects. This is a personal convention. You may choose any parameter names you wish to identify THETA, ETA and ERR/EPS in the control stream.

$PROB theophylline pharmacodynamics extended control stream
$DATA theopd.dat IGNORE #
$INPUT ID TIME THEO AGE WT GEND RACE DIAG PEFR=DV
$ESTIM PRINT=1 POSTHOC
MSFO=theopd.msf
$COV
$THETA (0,150.,) ; popE0
$THETA (0,200.,) ; popEMAX
$THETA (.001,10,) ; popEC50
$OMEGA 0.5 ; etaE0
$OMEGA 0.5 ; etaEMAX
$OMEGA 0.5 ; etaEC50
$SIGMA 100 ; errSD
$PRED
E0=pope0*EXP(etae0)
EMAX=popemax*EXP(etaemax)
EC50=popec50*EXP(etaec50)
Y = E0 + EMAX*THEO/(THEO+EC50) + errsd
$TABLE ID TIME THEO AGE WT GEND RACE DIAG
E0 EMAX EC50 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 an $PRED, $PK, $ERROR, $DES, $AES record. After translation the extended control stream example will be identical to the standard control stream example.

Using ESN's extended control streams

There are two options for using ESN's extended control streams:

Use it manually and/or in conjunction with Wings for NONMEM
Automatically translate between a standard control stream and extended control stream.

When using extended control stream options manually, you may change back and forth between THETA, ETA, and ERR/EPS values through the following two menu options:

NONMEM
- Extended Control Stream Options
  - Change THETA, ETA,EPS to WFN parameter names

NONMEM
- Extended Control Stream Options
  - Change WFN parameter names to THETA, ETA, EPS

The other option is to automate extended control stream translation. This opens files with the extended control stream parameter names filled in, and then saves as a standard control stream. Unlike WFN, mixing extended control stream variable names and standard THETA(1), ETA(1), EPS(1) is not well supported. While you may enter THETA(1) into the control stream, upon save, this is change to the label for THETA(1), like popE0. Automating extended control stream may be toggled with:

NONMEM
- Extended Control Stream Options
  - Translate Extended Control Streams to Normal Control Streams\; Open Extended

Emacs Speaks NONMEM differences/options

Mu variable referencing (not implemented in WFN)

NONMEM 7 introduces MU variable referencing (described here). Each MU_i variable mus be associated with an ETA, and each MU_i must have a relationship that is of the form MU_i+ETA(i). For this reason, an additional translation has been defined in the extended control stream when using EsN, that is:

MU_eta_variable_label is translated to MU_i
MU+eta_variable_label is translated to MU_i+ETA(i).

For example, if the following $OMEGA block is defined,

$OMEGA 0.5 ; etaE0
$OMEGA 0.5 ; etaEMAX
$OMEGA 0.5 ; etaEC50

The following table details the translations that may occur:

Original Value	Extended Control Stream
MU_1 = log(THETA(1))	MU_etaE0 = log(THETA(1))
E0 = EXP(MU_1+ETA(1))	E0 = EXP(MU_etaE0+etaE0)
E0 = EXP(MU_1+ETA(1))	E0 = EXP(MU+etaE0)
E0 = EXP(ETA(1)+MU_1)	E0 = EXP(etaE0+MU_etaE0)
E0 = EXP(ETA(1)+MU_1)	E0 = EXP(etaE0+MU)

A full example of an extended control stream is:

$PROB theophylline pharmacodynamics extended control stream
$DATA theopd.dat IGNORE #
$INPUT ID TIME THEO AGE WT GEND RACE DIAG PEFR=DV
$ESTIM PRINT=1 POSTHOC
MSFO=theopd.msf
$COV
$THETA (0,150.,) ; popE0
$THETA (0,200.,) ; popEMAX
$THETA (.001,10,) ; popEC50
$OMEGA 0.5 ; etaE0
$OMEGA 0.5 ; etaEMAX
$OMEGA 0.5 ; etaEC50
$SIGMA 100 ; errSD
$PRED
mu_etae0 = log(pope0)
mu_etaemax = log(popemax)
mu_etaec50 = log(popec50)
E0=EXP(mu+etae0)
EMAX=EXP(mu+etaemax)
EC50=EXP(mu+etaec50)
Y = E0 + EMAX*THEO/(THEO+EC50) + errsd
$TABLE ID TIME THEO AGE WT GEND RACE DIAG
E0 EMAX EC50 Y
NOPRINT ONEHEADER FILE=theopd.fit

This is equivalent to a standard control stream:

$PROB theophylline pharmacodynamics extended control stream
$DATA theopd.dat IGNORE #
$INPUT ID TIME THEO AGE WT GEND RACE DIAG PEFR=DV
$ESTIM PRINT=1 POSTHOC
MSFO=theopd.msf
$COV
$THETA (0,150.,) ; popE0
$THETA (0,200.,) ; popEMAX
$THETA (.001,10,) ; popEC50
$OMEGA 0.5 ; etaE0
$OMEGA 0.5 ; etaEMAX
$OMEGA 0.5 ; etaEC50
$SIGMA 100 ; errSD
$PRED
mu_1 = log(THETA(1))
mu_2 = log(THETA(2))
mu_3 = log(THETA(3))
E0= EXP(mu_1+ETA(1))
EMAX= EXP(mu_2+ETA(2))
EC50= EXP(mu_3+ETA(3))
Y = E0 + EMAX*THEO/(THEO+EC50) + EPS(1)
$TABLE ID TIME THEO AGE WT GEND RACE DIAG
E0 EMAX EC50 Y
NOPRINT ONEHEADER FILE=theopd.fit

Optional Skipping of variable names

When using PLT tools, you may wish to add comments that a read in the brief summary pdf file that will include a description of the parameter estimated. According to PLT tools' manual, any comment that is coded with ;C will be included in this file. The following code would be recognized by PLT tools:

$THETA (0,150.,)  ;C THETA(1) - popE0
$THETA (0,200.,)  ;C THETA(2) - popEMAX
$THETA (.001,10,) ;C THETA(3) - popEC50
$OMEGA 0.5 ;C ETA(1) - etaE0
$OMEGA 0.5 ;C ETA(2) - etaEMAX
$OMEGA 0.5 ;C ETA(3) - etaEC50
$SIGMA 100 ;C EPS(1) - errSD

After being recognized, the following text will be added to the brief summary:

THETA(1) - popE0
THETA(2) - popEMAX
THETA(3) - popEC50
ETA(1) - etaE0
ETA(2) - etaECMAX
ETA(3) - etaEC50
EPS(1) - errSD

which may be more clear than other types of labeling. According to Wings-for-NONMEM, these would all would be invalid labels since they are all C variable labels. In Emacs Speaks Statistcs, however, this initial C THETA, C ETA, or C EPS can be ignored, and the variables would still have the names popE0, popEMAX, etc.

With this in mind, the following control stream would still be valid:

$PROB theophylline pharmacodynamics extended control stream
$DATA theopd.dat IGNORE #
$INPUT ID TIME THEO AGE WT GEND RACE DIAG PEFR=DV
$ESTIM PRINT=1 POSTHOC
MSFO=theopd.msf
$COV
$THETA (0,150.,)  ;C THETA(1) - popE0
$THETA (0,200.,)  ;C THETA2 - popEMAX
$THETA (.001,10,) ;C THETA[3] - popEC50
$OMEGA 0.5 ;C ETA(1) - etaE0
$OMEGA 0.5 ;  ETA(2) - etaEMAX
$OMEGA 0.5 ;C OMEGA3 -  etaEC50
$SIGMA 100 ;C SIGMA1 errSD
$PRED
E0=pope0*EXP(etae0)
EMAX=popemax*EXP(etaemax)
EC50=popec50*EXP(etaec50)
Y = E0 + EMAX*THEO/(THEO+EC50) + errsd
$TABLE ID TIME THEO AGE WT GEND RACE DIAG
E0 EMAX EC50 Y
NOPRINT ONEHEADER FILE=theopd.fit

Overall, Emacs Speaks NONMEM would ignore:

Any C's after the initial comment
THETA
THETA#
THETA(#)
THETA[#]
THETA{#}
ETA
ETA#
ETA(#)
ETA[#]
ETA{#}
OMEGA
OMEGA#
OMEGA(#)
OMEGA[#]
OMEGA{#}
EPS
EPS#
EPS(#)
EPS[#]
EPS{#}
ERR
ERR#
ERR(#)
ERR[#]
ERR{#}
SIGMA
SIGMA#
SIGMA(#)
SIGMA[#]
SIGMA{#}

Where # represents an integer.

Note that if you run PLT tools, and use the ;C comment to include the $THETA, $OMEGA and $SIGMA labels, the final document may be little confusing. For example, with:

$THETA (0,150.,)  ;C THETA(1) - popE0
$THETA (0,200.,)  ;C THETA2 - popEMAX
$THETA (.001,10,) ;C THETA[3] - popEC50
$OMEGA 0.5 ;C ETA(1) - etaE0
$OMEGA 0.5 ;C  ETA(2) - etaEMAX
$OMEGA 0.5 ;C OMEGA3 -  etaEC50
$SIGMA 100 ;C SIGMA1 errSD

This would become:

ETA (0,150.,)  ;C THETA(1) - popE0
ETA (0,200.,)  ;C THETA2 - popEMAX
ETA (.001,10,) ;C THETA[3] - popEC50
EGA 0.5 ;C ETA(1) - etaE0
EGA 0.5 ;C  ETA(2) - etaEMAX
EGA 0.5 ;C OMEGA3 -  etaEC50
GMA 100 ;C SIGMA1 errSD

PLT tools 2.3.0 build 1589 takes drops the first 3 characters of the line recognized to be have comment text. Therefore the $THETA blocks becomes ETA, though it does not code for ETA variables. One way to overcome this is by having the code on each comment on a line without the record. In this example, we would have:

$THETA
       (0,150.,)  ;C THETA(1) - popE0
       (0,200.,)  ;C THETA2 - popEMAX
       (.001,10,) ;C THETA[3] - popEC50
$OMEGA
       0.5 ;C ETA(1) - etaE0
       0.5 ;C  ETA(2) - etaEMAX
       0.5 ;C OMEGA3 -  etaEC50
$SIGMA
       100 ;C SIGMA1 errSD

would result in unambiguous comments in the Brief Summary pdf:

    (0,150.,)  ;C THETA(1) - popE0
    (0,200.,)  ;C THETA2 - popEMAX
    (.001,10,) ;C THETA[3] - popEC50
    0.5 ;C ETA(1) - etaE0
    0.5 ;C  ETA(2) - etaEMAX
    0.5 ;C OMEGA3 -  etaEC50
    100 ;C SIGMA1 errSD

As of PLT tools 2.3.0 build 1589, this is no longer an issue (thanks Dennis!)

Parameter Names that are not allowed

Emacs Speaks NONMEM does not allow certain reserved keywords to be variable labels. For example EXP and DEXP are reserved in NONMEM control streams to have a specific meaning, and cannot be assigned to a variable label.

Parameter Names in the ZERO option

In addition to specifying variables in the $PK or $PRED portion of the control stream, Emacs Speaks NONMEM allows variable labels in the ZERO= option of the $ESTIMATION record, For example:

$PROB theophylline pharmacodynamics extended control stream
$DATA theopd.dat IGNORE #
$INPUT ID TIME THEO AGE WT GEND RACE DIAG PEFR=DV
$ESTIM PRINT=1 METHOD=HYBRID ZERO=(etaE0)
MSFO=theopd.msf
$COV
$THETA (0,150.,) ; popE0
$THETA (0,200.,) ; popEMAX
$THETA (.001,10,) ; popEC50
$OMEGA 0.5 ; etaE0
$OMEGA 0.5 ; etaEMAX
$OMEGA 0.5 ; etaEC50
$SIGMA 100 ; errSD
$PRED
E0=pope0*EXP(etae0)
EMAX=popemax*EXP(etaemax)
EC50=popec50*EXP(etaec50)
Y = E0 + EMAX*THEO/(THEO+EC50) + errsd
$TABLE ID TIME THEO AGE WT GEND RACE DIAG
E0 EMAX EC50 Y
NOPRINT ONEHEADER FILE=theopd.fit

On save, the $ESTIM record is translated to:

$ESTIM PRINT=1 METHOD=HYBRID ZERO=(1)

This is only occurs when Emacs Speaks NONMEM handles Extended Control stream translation is enabled.

This feature may also be toggled at:

NONMEM
- Extended Control Stream Options
  - Translate extended parameter names names in ZERO=(x)

Changing Parameter Names

If you wish to change the popE0 parameter name to E0, editing the label causes all of the parameter names referenced in the document to change without any extra effort. This option may be toggled at:

NONMEM
- Extended Control Stream Options
  - While editing parameter names, update names remaining control stream

Parameter Name Highlighting

When this option is enabled, parameter names are highlighted in the control-stream, making them easier to identify.

This may be toggled at:

NONMEM
- Extended Control Stream Options
  - Highlight Extended Control Stream Parameter Names

Lower case preference

When opening a normal control stream as an extended control stream, there is an option to have the records in lower case instead of upper case; This may be toggled at:

NONMEM
- Extended Control Stream Options
  - When opening extended, prefer records in lower case

esnm

Emacs Speaks NONMEM

Extended Control Stream

Overview

Key Definitions

Parameter Names

Extended Control Stream

Example: Standard Control Stream

Example: Extended Control Stream

Using ESN's extended control streams

Emacs Speaks NONMEM differences/options

Mu variable referencing (not implemented in WFN)

Optional Skipping of variable names

Parameter Names that are not allowed

Parameter Names in the ZERO option

Changing Parameter Names

Parameter Name Highlighting

Lower case preference