61  Expansions on Abbreviated and Verbatim Code and Other Items (NM72,NM73,NM74,NM75)

Introduction to NONMEM 7.6.0

Author

Robert J. Bauer

Published

June 1, 2025

1 FORTRAN 95 Considerations

The greatest changes of NONMEM 7.1 are the renaming of many of the internal variables, and their repackaging from COMMON blocks to Modules. Whereas formerly, a variable in a common block may have been referenced using verbatim code as:

COMMON/PROCM2/DOSTIM,DDOST(30),D2DOST(30,30)

Now, you would reference a variable as follows:

USE PROCM_REAL,ONLY: DOSTIM

And you may reference only that variable that you need, without being concerned with order.

In addition, FORTRAN 95 allows you to use these alternative symbols for logical operators:

Example:

Fortran 77:

IF(ICALL.EQ.3) THEN
WRITE(50,*) CL,V
ENDIF

Fortran 95:

IF(ICALL==3) THEN
WRITE(50,*) CL,V
ENDIF

The list of operators are:

Name of logical operator Fortran 77 Fortran 95
Equal to .EQ. ==
Not equal to .NE. /=
Greater than .GT. >
Greater than or equal to .GE. >=
Less than .LT. <
Less than or equal to .LE. <=

In FORTRAN 95, the continuation marker & must be on the line to be continued, rather than at the sixth position of the continued line:

Fortran 77:

CL=THETA(6)*GENDER+
xTHETA(7)**AGE

Fortran 95:

CL=THETA(6)*GENDER+ &
THETA(7)**AGE

This affects verbatim code and user-written subroutines. For example, an NMVI version of CCONTR would be written as follows:

SUBROUTINE CCONTR (I,CNT,P1,P2,IER1,IER2)
PARAMETER (LTH=40,LVR=30,NO=50)
COMMON /ROCM0/ THETA (LTH)
COMMON /ROCM4/ Y
DOUBLE PRECISION CNT,P1,P2,THETA,Y,W,ONE,TWO
DIMENSION P1(*),P2(LVR,*)
DATA ONE,TWO/1.0D+00,2.D+00/
IF (I.LE.1) RETURN
W=Y
Y=(Y**THETA(3)-ONE)/THETA(3)
CALL CELS (CNT,P1,P2,IER1,IER2)
Y=W
CNT=CNT-TWO*(THETA(3)-ONE)*LOG(Y)
RETURN
END

Whereas in NM7, it would be written as:

SUBROUTINE CCONTR(I,CNT,P1,P2,IER1,IER2)
USE SIZES, ONLY: ISIZE,DPSIZE
USE ROCM_REAL, ONLY: THETA=>THETAC,Y=>DV_ITM2
USE NM_INTERFACE,ONLY: CELS
IMPLICIT NONE
INTEGER(KIND=ISIZE), INTENT(IN OUT) :: I,IER1,IER2
REAL(KIND=DPSIZE), INTENT(IN OUT) :: CNT,P1(:),P2(:,:)
REAL(KIND=DPSIZE) :: ONE,TWO,W
DATA ONE,TWO/1.00D+00,2.00D+00/
SAVE
IF (I.LE.1) RETURN
W=Y(1)
Y(1)=(Y(1)**THETA(3)-ONE)/THETA(3)
CALL CELS (CNT,P1,P2,IER1,IER2)
Y(1)=W
CNT=CNT-TWO*(THETA(3)-ONE)*LOG(Y(1))
RETURN
END

2 Continuation indicator is allowed in abbreviated code (non-verbatim) lines (NM73)

As of NONMEM 7.3.0, extra long lines may be continued using an & at the end of the line:

CL=EXP(THETA(1)*WERT &
+EPS(1))

The total number of characters in the resulting concatenated line may not exceed FSD (default set to 67000 in sizes.f90). In fact, the continuation marker & may be used on record lines as well. If the ampersand at the end of a line is not to be interpreted as a continuation marker, but as a part of the record, then, place a ; after it. For example,

FORMAT=s1PE15.8:160& ;

3 Alternative Inputs for $OMEGA and $SIGMA Values: VARIANCE/ CORRELATION/ CHOLESKY (NM72)

In NONMEM 7.2.0, OMEGA and SIGMA elements may be entered in forms other than the default variance diagonal elements and covariance off-diagonal elements. Diagonal elements may also be entered as standard deviation, and off-diagonal elements may be entered as correlation values. Options are

  • VARIANCE/STANDARD to indicate form of diagonal elements
  • COVARIANCE/CORRELATION to indicate form of off-diagonal elements
  • CHOLESKY for inputting blocks of OMEGAS or SIGMAS in their Cholesky form.

Examples:

$OMEGA BLOCK(2) ; or $OMEGA VARIANCE COVARIANCE BLOCK(2)
0.64
-0.2402 0.58

$OMEGA STANDARD BLOCK(2)
0.8
-0.24 0.762

$OMEGA STANDARD CORRELATION BLOCK(2)
0.8
-0.394 0.762

$OMEGA VARIANCE CORRELATION BLOCK(2)
0.64
-0.394 0.58

$OMEGA CHOLESKY BLOCK(2)
0.8
-0.3 0.7

$SIGMA 0.3 STANDARD 0.8 STANDARD 0.3 VARIANCE

These input options do not affect how estimated OMEGAs and SIGMAs are outputted.

With NONMEM 7.3.0, there are new features for abbreviated code and the $ABBR record. Each is discussed in greater detail in the on-line help and Guide VIII:

4 Repeated SAME BLOCK for $OMEGA and $SIGMA Records (NM73)

No need to repeat multiple SAME block segments:

$OMEGA BLOCK(2) SAME(3)

Is equivalent to

$OMEGA BLOCK(2) SAME
$OMEGA BLOCK(2) SAME
$OMEGA BLOCK(2) SAME

The SAME(m) feature is also available for $SIGMA.

$SIGMA BLOCK(2) SAME(3)

5 Repeated Value Inputs for $THETA, \(`OMEGA`, and `\)SIGMA` Records (NM73)

As of NM73, repeated inputs of $THETA be entered as follows:

Long-hand:

$THETA 2 2 2 2 (0.001,0.1,1000) (0.001,0.1,1000) (0.001,0.1,1000)
       (0.5 FIXED) (0.5 FIXED)

Short-hand:

$THETA (2)x4 (0.001,0.1,1000)x3 (0.5 FIXED)x2

Where xn means to replicate n times. The item to be repeated must always be in parentheses, and the xn must always be immediately after the item, not before it (4x(0.2) is not permitted).

Repeated inputs of $OMEGA or $SIGMA may be entered as follows:

$OMEGA BLOCK(6)
0.1
0.01 0.1
(0.01)x2 0.1
(0.01)x3 0.1
(0.01)x4 0.1
(0.01)x5 0.1

The VALUES(diag,odiag) feature allows one to set up initial values with diagonals diag and off-diagonals odiag. The above example could have been entered as

$OMEGA BLOCK(6) VALUES(0.1,0.01)

For fixed block (such as for omega priors):

$OMEGA BLOCK(6) FIX VALUES(0.15,0.0)

6 SCALE option for $OMEGA and $SIGMA (NM760)

As of nm760, you may have your OMEGA or SIGMA values multiplied by a SCALE value. The SCALE value takes into affect on any OMEGA or SIGMA values that come after it in the record:

$OMEGA 0.5 0.7 SCALE(2.0) 0.8 0.9 SCALE(1.5) 0.1 0.2

is equivalent to

$OMEGA 0.5 0.7 1.6 1.8 0.15 0.3

Other examples:

$OMEGAP SCALE(0.7) BLOCK(4) FIX VALUES(0.5,0.01)

is equivalent to:

$OMEGAP BLOCK(4) FIX VALUES(0.35,0.07)
$OMEGAP SCALE(0.7) BLOCK(4) FIX
0.5
0.01 0.5
SCALE(2.5)
0.02 0.02 0.003

Is equivalent to

$OMEGAP SCALE(0.7) BLOCK(4) FIX
0.5
0.01 0.5
0.05 0.05 0.0075

The SCALE is most useful when it is desired to scale an informed prior OMEGA from a previous analysis that differs from NONMEM’s normal treatment. For example, you may wish to scale the omega prior by (df-p-1)/df, where df=degrees of freedom, and p=dimension of omega block. Rather than always re-calculate by hand, you can change the scale on the fly.

7 $ABBR DECLARE feature for abbreviated code (NM73)

Integers and arrays may be declared and used in abbreviated code:

$ABBR DECLARE DOSE(100),DOSETIME(100)
$ABBR DECLARE INTEGER I

8 $ABBR REPLACE feature for abbreviated code (NM73-NM75)

Any character string may be replaced. In particular, this allows for symbolic labeling to THETAs, etas, and epsilons. As an example, subscripts to THETAS and ETAS can be given symbolic names:

$ABBR REPLACE THETA(CL)=THETA(4)
$ABBR REPLACE ETA(CL)=ETA(5)
CL=THETA(CL)*EXP(ETA(CL))

Replacement with selection by data item and parameter is permitted:

$ABBR REPLACE THETA(OCC)=THETA(4,7,10)
$PK
KA=THETA(OCC)

which is equivalent to

$PK
IF (OCC==1) KA=THETA(4)
IF (OCC==2) KA=THETA(7)
IF (OCC==3) KA=THETA(10)

Another example:

$ABBR REPLACE THETA(SID_KA)=THETA(4,6)
$ABBR REPLACE THETA(SID_CL)=THETA(5,7)
$PK
KA=THETA(SID_KA)
CL=THETA(SID_CL)

which is equivalent to

$PK
IF (SID==1) KA=THETA(4)
IF (SID==2) KA=THETA(6)
IF (SID==1) CL=THETA(5)
IF (SID==2) CL=THETA(7)

A list of numbers may be given as:

$ABBR REPLACE THETA(SID_KA)=THETA(4,7,10,13)

or by the short-hand

$ABBR REPLACE THETA(SID_KA)=THETA(,4 to 13 by 3)

At least one comma must appear, so NMTRAN knows it is a number list, not a variable name.

As of NM74, there is more flexibility of the BY variable: The : may be used in place of TO. Also,

$ABBR REPLACE THETA(SID_KA)=THETA(10:4 by 3)    ; order: 10,7,4
$ABBR REPLACE THETA(SID_KA)=THETA(4 to 10 by -3) ; order: 10,7,4
$ABBR REPLACE THETA(SID_KA)=THETA(10 to 4)       ; order: 10,9,8,7,6,5,4

Another example:

Long-hand:

$ABBR REPLACE THETA(SID_KA)=THETA(4,7,10,13,25,29,33,37)

Short-hand:

$ABBR REPLACE THETA(SID_KA)=THETA(,4 to 13 by 3,25 to 37 by 4)

Also, a series of alias names may be conveniently defined (NM74):

$ABBR REPLACE THETA(CL,V1,Q,V2)=THETA(1 TO 4)
$ABBR REPLACE ETAQQ(CL,V1,Q,V2)=ETA(1 TO 4)

You may use them in abbreviated code, and, as of NM74, in $TABLE as well:

CL=EXP(THETA(CL)+ETAQQ(CL))

$TABLE ID TIME DV IPRED ETAQQ(CL) ETAQQ(V1) ETAQQ(Q) ETAQQ(V2)

The symbolic label substitutions will appear in the NONMEM report file and $TABLE outputs, for example (NM74):

THETA - VECTOR OF FIXED EFFECTS PARAMETERS *********

        THETA(CL) THETA(V1) THETA(Q)  THETA(V2)

        1.68E+00  1.59E+00  8.13E-01  2.37E+00

 OMEGA - COV MATRIX FOR RANDOM EFFECTS - ETAS ********

        ETAQQ(CL) ETAQQ(V1) ETAQQ(Q)  ETAQQ(V2)

 ETAQQ(CL)
+        1.65E-01

 ETAQQ(V1)
+        4.62E-03  1.34E-01

 ETAQQ(Q)
+        6.35E-03  1.69E-02  2.14E-01

 ETAQQ(V2)
+       -1.53E-02  1.26E-02  5.33E-02  1.63E-01

To turn off symbolic label substitution in the reporting of estimates, set $EST NOSUB=1 for a particular estimation problem. To turn off label substitution in $TABLE outputs, set $TABLE NOSUB=1 for that particular table. Also for $SCAT NOSUB=1 ETAQQ(V1) VS ETAQQ(CL) for example.

To set the default NOSUB for the entire problem, specify the following $DEFAULT (or $DEFAULTS) record:

$DEFAULT NOSUB=1

NOSUB also accepts a -1 to indicate revert to NONMEM default, which is to treat -1 as a 0. The NOSUB default setting is in effect throughout the control stream file, until another $DEFAULT record setting NOSUB is encountered.

Symbolic label substitutions will not be made in the additional output files (*.ext, .phi, etc), to maintain their third party software readability. However, see the utility lblr in I.97 lblr: Insert User-Defined Labels in Additional Files (NM75) for implementing post-NONMEM-run label substitutions.

9 Symbolic Label Substitutions at $THETA, \(`OMEGA`, and `\)SIGMA` records (NM75)

A very easy way to apply symbolic label substitutions to THETAs is by defining the labels at the $THETA record:

$THETA
CL=(0.0,7.0)
V1=(5.0 fixed)

etc. This is equivalent to

$ABBR REPLACE THETA(CL)=THETA(1)
$ABBR REPLACE THETA(V1)=THETA(2)

Once defined, the $PK or $PRED code can use these definitions:

TVCL=THETA(CL)

To apply symbolic labels to OMEGAS:

$OMEGA BLOCK(4)
ECL= 0.3
EV1= 0.01 0.35
EQ= 0.01 0.01 0.54
EV2= 0.01 0.01 0.01 0.67

Or, for diagonals,

$OMEGA
ECL= 0.3
EV1= 0.35
EQ= 0.54
EV2= 0.67

Then, these take effect on etas and MU_’s:

MU_ECL=THETA(CL)
CL=EXP(MU_ECL+ETA(ECL))

Similar symbolic labels may be applied to SIGMAS/Epsilons. Consider the following example code:

$THETA
V1=(0.0,7.0) CL=(0.0,7.0) Q=(0.0,7.0) V2=7

$OMEGA BLOCK(4)
ECL= 0.3
EV1= 0.01 0.35
EQ= (0.01)X2 0.54
EV2= (0.01)X3 0.67

$SIGMA
RSW=(0.6 ) ;[P]

$THI
THETA(CL)=LOG(THETAI(CL))
THETA(V1)=LOG(THETAI(V1))
THETA(Q)=LOG(THETAI(Q))
THETA(V2)=LOG(THETAI(V2))

$THR
THETAR(CL)=LOG(THETA(CL))
THETAR(V1)=LOG(THETA(V1))
THETAR(Q)=LOG(THETA(Q))
THETAR(V2)=LOG(THETA(V2))

$PK
MU_ECL=THETA(CL)
MU_EV1=THETA(V1)
MU_EQ=theta(Q)
MU_EV2=THETA(V2)
CL=DEXP(MU_ECL+ETA(ECL))
V1=DEXP(MU_EV1+ETA(EV1))
Q=DEXP(MU_EQ+ETA(EQ))
V2=DEXP(MU_EV2+ETA(EV2))
S1=V1

$ERROR
Y = F + F*EPS(RSW)

Notice the $THETA, $OMEGA and $SIGMA records must be placed ahead of any records that use the symbolic label. So, these records must be placed before $THI, $THR, $PK, and $ERROR. Also, notice that the position of CL V1 in $PK in reverse order relative to the associated etas in $OMEGA. Thus, the inter-subject variability of CL is ETA(1), and its fixed effect is THETA(2). The user no longer needs to consider the numeric ordering of THETAs and etas, however, and just utilize the symbols, and NMTRAN will map out everything correctly in the final FSUBS routine. If later, you wish to add a theta, you can place it anywhere in the $THETA record (its position in $THETA defines its numerical index), and not be concerned about renumbering the THETAs in the code.

If specifying the Omega or Sigma values using VALUES(), then you can enter

$OMEGA BLOCK(4) NAMES(ECL,EV1,EQ,EV2) VALUES(0.03,0.01)

VALUES() must come after NAMES() in the $OMEGA record.

Similarly, you may find it more convenient to specify Theta symbols as follows:

$THETA NAMES(V1,CL,Q,V2)
(0.0,7.0) (0.0,7.0) (0.0,7.0) 7

For dynamic, or implicit mapping of labels, such as for various occasions, these still need to be done via the $ABBR REPLACE record.

10 Easier Inter-occasion variability modeling (NM73)

Abbreviated code Replacement Feature and Repeated Feature of $OMEGA may be combined for easier Inter-occasion variability modeling. For example,

$ABBR REPLACE ETA(OCC_CL)=ETA(4,7,10)
;when OCC=1, eta(4) to be used: when OCC=2, eta(7) to be used, etc.
$ABBR REPLACE ETA(OCC_V) =ETA(5,8,11)
$ABBR REPLACE ETA(OCC_KA)=ETA(6,9,12)
$PK
CL=TVCL*EXP(ETA(1)+ETA(OCC_CL))
V =TVV *EXP(ETA(2)+ETA(OCC_V))
KA=TVKA*EXP(ETA(3)+ETA(OCC_KA))
$OMEGA BLOCK(3) 0.1 0.01 0.1 0.01 0.01 0.1
$OMEGA BLOCK(3) 0.03 0.001 0.03 0.001 0.001 0.03
$OMEGA BLOCK(3) SAME(2); Repeat OMEGA BLOCK(3) SAME twice

In the above example, the NMTRAN parses the variable name OCC_CL at the underscore, and determines that there is a data item called OCC with which to associate the variable with the etas listed.

11 Symbolic Label Substitutions of Model Compartments (NM73,NM75)

As of NM73, one can readily substitute compartment designations by defining appropriate $ABBR REPLACE statements, such as:

$ABBR REPLACE A(CENTRAL)=A(1)
$ABBR REPLACE DADT(CENTRAL)=DADT(1)

The names designated in $ABBR REPLACE do not need to be the same as those designated in the $MODEL record, although this may cause reader’s confusion if you do not do this.

As of NM75, compartment-name symbols defined in $MODEL are automatically available for substitution without requiring $ABBR RECORD definitions. For example:

$MODEL
     COMP=(GUT,DEFDOS)
     COMP=(CENTRAL,DEFOBS)
     COMP=(PERI)

allows susbsitutions to be made for A(GUT), DADT(GUT), A(CENTRAL), DADT(CENTRAL), etc, so you may use these symbols in your NMTRAN code, for example:

$DES
DADT(GUT)=-KA*A(GUT)
DADT(CENTRAL)=KA*A(GUT)-(KCP+KC0)*A(CENTRAL)+KPC*A(PERI)
DADT(PERI)=KCP*A(CENTRAL)-KPC*A(PERI)
...
$ERROR
IPRED=A(CENTRAL)/S2

12 $FORMAT FMTN=3 (default) (NM75)

You may now display any significant digits for THETAs, OMEGAs, and SIGMAs results, and variance-covariance of estimates, listed in the NONMEM report file. The FMTN is the number of significant digits (which is by legacy and default 3), between 3 and 23. This also applies to $TABLE outputs to the NONMEM report file. The FORTRAN format will be formed as 1PE{FMTN+6}.{FMTN-1}. For example FMTN=6 will be 1PE12.5. If you wish G field format, set the FMTN to a negative value. For example FMTN=-4 will be 1PG10.3.

It is recommended that you place the $FORMAT record immediately after the $PROB record:

$PROB My problem
$FORMAT FMTN=5

This FMTN precision format will be in effect for outputs of all problems, until another $FORMAT record is given for a new $PROB in the control stream.

13 DO WHILE enhancement (NM73)

DOWHILE may now be used in all blocks of abbreviated code. If a variable is used as a DOWHILE loop variable, it must be declared:

$ABBR DECLARE DOWHILE I

Recursive random variables (“dowhile recursive variables”) may be computed in DOWHILE blocks, as well as in ordinary abbreviated code. A new example (..\examples\sumdosetn.ctl) uses DOWHILE for dose super-imposition in a transit compartment, and includes the following:

...
$abbr declare dosetime(100),dose(100)
$abbr declare dowhile i
$abbr declare dowhile ndose

$PK
CALLFL=-2
IF (NEWIND < 2) NDOSE=0

IF (AMT > 0 .and. cmt==1) THEN
 NDOSE=NDOSE+1
 dosetime(NDOSE)=TIME
 DOSE(NDOSE)=AMT
ENDIF
...
$DES
INPT=0
I=1
DOWHILE (I<=NDOSE)
IPT=0
IF (T>=dosetime(I)) IPT=DOSE(I)*(T-dosetime(I))**NN*EXP(-KTR*(T-dosetime(I)))
INPT=INPT+IPT
I=I+1
ENDDO

See also ssaddl.ctl, ssonedose.ctl, and ssmultidose.ctl for additional examples.

14 Subscripted Variables Enhancement (NM73)

Subscripts may be used with user-defined variables that are declared to be arrays using the $ABBR DECLARE record, and also with certain reserved variables such as THETA. Subscripts may be integer variables and expressions. For example,

$ABBR DECLARE INTEGER IND
$ABBR DECLARE X(10)
$PK
IND=1
X(IND)=THETA(IND+1)

In general random variables such as ETA may not have variables as subscripts. See section SUBSCRIPTED VARIABLES of the help entry for ABBREVIATED CODE for a more complete list.

15 Autocorrelation (CORRL2) (NM73)

Correlation of residual variables using CORRL2 may now be written in abbreviated code. For example (..\examples\ar1mod.ctl):

$ABBR DECLARE T(NO)
$ABBR DECLARE DOWHILE J
$ABBR DECLARE INTEGER I
...
$ERROR
IF(NEWIND.NE.2)I=0
IF(MDV.EQ.0)THEN
I=I+1
T(I)=TIME
J=1
DOWHILE (J<=I)
CORRL2(J,1)=EXP(-THETA(4)*(TIME-T(J)))
J=J+1
ENDDO
ENDIF

A new example is provided. Simulation with autocorrelation is also possible (..\examples\ar1newsim.ctl).

16 MOD Function (NM73)

The Fortran intrinsic function MOD may now be used in abbreviated code:

k=MOD(i,j)

MOD returns the remainder when i is divided by j. The variables i and j must be either both integer or both real. For example,

TAD = MOD(TIME,24.0D+00)

will make the 24 a double precision variable, in keeping with the data type of TIME.

This function should not be involved in evaluation of the objective function.

17 MIN, MAX Functions (NM73)

The Fortran intrinsic functions MIN and MAX may now be used in abbreviated code:

DVALUE=MAX(VAL1,VAL2,VAL3...)

However, this function should not be involved in evaluation of the objective function. IF THEN statements should be used for those, for example:

DVALUE=VAL1
IF(VAL2>DVALUE) DVALUE=VAL2
IF(VAL3>DVALUE) DVALUE=VAL3

Also, ensure that if any data items are used in the MAX or MIN argument, that this data item appeared elsewhere in the code block. For example, consider a data item called AGE,

LAGE=LOG(AGE)
AGE2=MAX(AGE,0.0)

18 GAMLN Function (NM73)

The GAMLN function returns an accurate evaluation of the logarithm of the gamma function. It can be used in the evaluation the factorial:

FAC=exp(gamln(x+1.0))

Where

FAC=X!=X*(X-1)*(X-2)...*1

It is more accurate that the Stirling’s approximation, and may be used in abbreviated code in the evaluation of the objective function.

19 RANDMT Function (NM75)

The RANDMT function returns a random variable, than can be used during estimation.

rval=RANDMT(N)

Where

  • N: integer degrees of freedom
  • 0: get uniform random variable
  • N=1 or N>101: get normal random variable
  • N>1 and N<=100: get Student-t random variable with N-1 degrees of freedom

The random source is the same as that used internally by NONMEM during estimation (ICALL=2), such as for Monte Carlo EM and BAYES methods, with starting seed and random generator algorithm defined by $EST SEED and RANMETHOD (see RANMETHOD=[n|M|S|m|P] (default n=3) (NM72) and SEED=11456 (default) in I.38 Monte Carlo Importance Sampling EM). During simulation (ICALL=4), RANDMT uses source defined by the first seed, and random generating algorithm specified by RANMETHOD, defined on the $SIML record. During NPDE generation for diagnostic assessment, the RANMETHOD and SEED specified on the first $TABLE record is the source (RANMETHOD=[n|S|m|P] (default n=3) (NM72) SEED in I.17 $TABLE: Additional Statistical Diagnostics, Associated Parameters, and Output Format). Similarly, during the $CHAIN step, the $CHAIN SEED= and $CHAIN RANMETHOD= statements define the source (see $CHAIN Record).

During simulation, it is best to use the RANDOM(K,R) routine directly as described in the help guide (VIII.pdf), or via the probability density function generators (I.34 Probability Density Functions (NM742)).

20 RANDMTU Function (NM75)

The RANDMTU function returns a random variable.

rval=RANDMTU(N,SOURCE,STARTSEED,RANM)

Where

  • N: integer Degrees of freedom
  • 0: get uniform random variable
  • N=1 or N>101: get normal random variable
  • N>1 and N<=100: get Student-t random variable with N-1 degrees of freedom

SOURCE: Integer between 0 and 20, allowing the user to maintain up to 20 distinct seed sources. If SOURCE=0, it uses the default source. The default source is that specified for $EST .. SEED= ... RANMETHOD=... during estimation, or $SIML during simulation.

STARTSEED: Integer, which if not 0, causes initialization with the designated starting seed. STARTSEED should be set to 0 after this initialization. If SOURCE=0, this argument is ignored. If STARTSEED is <0, then the starting seed will be 10000*(seconds after midnight)+ABS(STARTSEED). The actual startseed is stored in RANDMTU_STARTSEED(SOURCE), module NM_BAYES_INT, accessible by using nonmem_reserved_general (see the example below).

RANM: Integer, indicating the type of random number generator algorithm to use (set at initialization when STARTSEED/=0), as follows:

If you wish to use the default random number generator relative to the present ICALL value, then set RANM to -1. This will use whatever random number generator has been specified in the $EST statement (ICALL=2), or $SIML statement (ICALL=4) to be used. If SOURCE=0, then this argument is ignored.

Random sources of RANDMTU are not properly preserved during Parallelization, unless SOURCE=0.

If you wish to use SOURCE=0, it is easier to simply call RANDMT, rather than RANDMTU(N,0,...):

rval=RANDMT(N)

Example: In the following, 2 random sources are used, with different starting seeds

$ERROR ; may also be used in other records
include nonmem_reserved_general
...
...
; Make sure NMTRAN is aware of RVAL1 and RVAL2, so it is accessible
; for $TABLE output

   RAVL1=0.0
   RVAL2=0.0
   RVAL3=0.0
   IF(NEWIND==0) THEN
; Initialize only at beginning of the data set.
; 3=t-distribution with DF=2
   RVAL1=RANDMTU(3,1,-1234,-1)
   write(*,*) RANDMTU_STARTSEED(1)
   RVAL2=RANDMTU(3,2,5678,-1)
   ENDIF
   RVAL1=RANDMTU(3,1,0,-1)
   RVAL2=RANDMTU(3,2,0,-1)
   RVAL3=RANDMT(3)

Note that calling RANDMT(N) (or equivalently RANDMTU(N,0,...)) did not require an initialization call (and would be ignored if you did), as this is under the control of $EST, $SIML, or $TABLE.

The RANDMTU random number generating system is independent of the CALL RANDOM() system. The RANMTU() routine has the flexibility to be used for estimation or simulation, and does not require its seed to be defined on the $SIML record, whereas RANDOM() can only be used during ICALL=4, and its seed must be defined on the $SIML record. During simulation, it is best to use the RANDOM(K,R) routine directly as described in the help guide (VIII.pdf), or via the probability density function generators (I.34 Probability Density Functions (NM742)).

21 Declaring Reserved Variables (NM73)

Some useful reserved variables are explicitly recognized by NMTRAN that can be used by the user. There are however many other variables that are generally internal to NONMEM, and often are not needed by users except occasionally, which are not explicitly recognized by NMTRAN, and so cannot be used in abbreviated code, but must be used with verbatim code (" at beginning of line). For example the variable ITER_REPORT is available that contains the present iteration number as reported to the console or NONMEM report file, that may be useful to be accessed within the $PK, $ERROR, or $PRED code. A convenient means of accessing this variable, as well as letting NMTRAN allow you to use that variable in abbreviated code is to place its MODULE definition in an include file that begins with the name NONMEM_RESERVED (case insensitive) at the beginning of the section you want to use it. For example, NONMEM_RESERVED_GENERAL in the ..\util directory has many quite useful variables listed, including ITER_REPORT, in the form of:

"C ITER_REPORT: Iteration number that is reported to output
"C (can be negative, if during a burn period).
"C BAYES_EXTRA, BAYES_EXTRA_REQUEST, used in example 8
" USE NMBAYES_REAL, ONLY: OBJI
" USE NMBAYES_INT, ONLY: ITER_REPORT,BAYES_EXTRA_REQUEST,BAYES_EXTRA
" USE PNM_CONFIG, ONLY: PNM_NODE_NUMBER
" USE NM_INTERFACE, ONLY: TFI,TFD

The user may use any one of these variables, such as shown in example 8:

$PK
include nonmem_reserved_general
BAYES_EXTRA_REQUEST=1
MU_1=THETA(1)
MU_2=THETA(2)
MU_3=THETA(3)
MU_4=THETA(4)
CL=DEXP(MU_1+ETA(1))
V1=DEXP(MU_2+ETA(2))
Q=DEXP(MU_3+ETA(3))
V2=DEXP(MU_4+ETA(4))
S1=V1
IF(BAYES_EXTRA==1 .AND. ITER_REPORT>=0 .AND. TIME==0.0) THEN
WRITE(50,*) ITER_REPORT,ID,CL,V1,Q,V2
ENDIF

Note the lack of needing to begin a line with " when using ITER_REPORT, BAYES_EXTRA_REQUEST, or BAYES_EXTRA, because NMTRAN “read” the nonmem_reserved_general file, and listed the variables declared in there as acceptable to use. A copy of the nonmem_reserved_general file is in the ..\util directory. It needs to be placed in the present run directory so NMTRAN has access to it. You could opt to copy only part of the list in nonmem_reserved_general according to need into any file with name starting with nonmem_reserved...

A list of useful variables and their meanings are also listed in ..\guides\useful_variables.pdf. However, the more complete list is in nonmem_reserved_general. Be careful in its use, as you have the ability to change the values of these reserved variables, and this could crash the system if you change the wrong thing.

Note also that the nonmem_reserved_general file may contain function declarations, such as TFI and TFD, which are convenient functions to easily convert an integer to text (“text from integer” TFI) or double precision value to text (“text from double” TFD). This is quite useful so that the compiler can catch a misuse of that function’s arguments.

If you wish to define your own function, and have the information about its proper use of arguments be conveyed upon its execution, so the compiler may detect errors, then one method is to package the definition of the function in a USE module, such as is done in the following example:

Myfuncmodule.f90 defines the functions mymin and mymax:

MODULE MYFUNCS
contains
function mymin(a,b,c,d,e)
integer mymin
integer a,b,c,d,e
mymin=min(a,b,c,d,e)
end function
function mymax(a,b,c,d,e)
integer mymax
integer a,b,c,d,e
mymax=max(a,b,c,d,e)
end function
END MODULE MYFUNCS

Nonmem_reserved_myfunc is the include file that declares its use:

" USE myfuncs, only: mymin,mymax

and the following control stream file uses the function:

$PROB THEOPHYLLINE POPULATION DATA

$INPUT      ID DOSE=AMT TIME CP=DV WT

$DATA       THEOPP

$SUBROUTINES ADVAN2 OTHER=myfuncmodule.f90

$PK
;THETA(1)=MEAN ABSORPTION RATE CONSTANT (1/HR)
;THETA(2)=MEAN ELIMINATION RATE CONSTANT (1/HR)
;THETA(3)=SLOPE OF CLEARANCE VS WEIGHT RELATIONSHIP (LITERS/HR/KG)
;SCALING PARAMETER=VOLUME/WT SINCE DOSE IS WEIGHT-ADJUSTED
include "nonmem_reserved_myfunc"

     CALLFL=1
     KA=THETA(1)+ETA(1)
     K=THETA(2)+ETA(2)
     CL=THETA(3)*WT+ETA(3)
     SC=CL/K/WT
I=mymin(1,2,3,4,5.0)
print *,'I ',I

$THETA (.1,3,5) (.008,.08,.5) (.004,.04,.9)
$OMEGA BLOCK(3) 6 .005 .0002 .3 .006 .4

$ERROR
     Y=F+EPS(1)

$SIGMA .4

If you use the wrong argument type (real instead of integer), or perhaps use the wrong number of arguments, the compiler will readily flag this.

22 Numerical Equality Comparison for IGNORE option in $DATA Record (NM73)

When the IGNORE option is used to filter records from the input file, the .EQ., =, .NE., and /= symbols perform literal string comparisons. To provide a numerical equality comparison, use .EQN. for numerical equals, and .NEN. for numerical not equals. For example

$DATA FILE=myfile.txt IGNORE=(OCC.EQN.1)

Will filter out all records for which the data item OCC is equal numerically to 1, even if it is stored as 1.0, or 1.00e+00, etc.

$DATA FILE=myfile.txt IGNORE=(OCC.EQ.1)

only filters out records for which OCC is literally '1'.

23 $DATA MISDAT (NM74)

You may wish to define a particular numerical value to indicate a missing data value in your data set, which is displayed on $TABLE table outputs, but is safely interpreted as 0 by other steps of NONMEM. To do this, set MISDAT at the $DATA record, for as many misdat labels you may need (up to 20):

$DATA mydatafile MISDAT=1.0E-99 MISDAT=1.0E-102

Any values in the data set that are one of the MISDAT values will be interpreted as 0 during estimation, simulations, etc., but upon output to tables, will have the MISDAT value, to keep track of missing data values (or other markings in the original data set).

24 $DATA REPL (NM75)

For clinical trial simulations, typically one creates a data file containing template subjects, which are to be replicated a number of times. The replication of the template subjects was often done in R or Excel, as NONMEM could not expand the data file in this way. As of NM75, NONMEM will replicate each subject REPL=n times, and then utilize this expanded data set. (Note that the NONMEM data set is typically the file FDATA generated by NM-TRAN, unless there is nothing for NM-TRAN to change and the format is supplied on the $DATA record, in which case the file named on the $DATA record is the NONMEM data set. See NONMEM Users Guide, Part IV.) For example, suppose a data file, called template.csv, contains 3 subjects, each one representing a particular covariate type, dosing type, and/or sample time pattern. The desire is that each of these subjects be replicated 100 times in the data set. This is done with the following record.

$DATA template.csv ignore=@ REPL=100

Make sure that the ID values of the template are integer valued. If the number of replications is greater than the difference between two consecutive ID values in the template, NONMEM will add a fractional value to each replicate subject, so that the integer portion of the ID is the original ID, and the fractional portion represents the replication number (NONMEM does not require integer valued ID’s, only unique ID numbers that have no more than 14 significant digits). Otherwise, the replicate ID’s will be integer incremented. To assure only integer ID’s are created, make sure the template ID’s are spaced by an amount greater than the number of replications desired for each subject.

To specify a different replication for each subject, a reserved data item has been introduced in nm75, called REPL_, the value of which will be used as the replication number for that subject. If the value is fractional, it will be truncated to the nearest integer. Only the REPL_ value of the first record of each individual will be used to determine its replication. For example, in the following data set:

Control stream:

$INPUT ID TIME AMT RATE EVID MDV DV REPL_
$DATA warfarin.dat ignore=C

Data file:

CID TIME     AMT   RATE EVID MDV DV  REPL_
1.0 0.0     70.0   0.0   1   1  0.0   2
1.0 0.0      0.0   0.0   0   0  1.0   .
1.0 0.5      0.0   0.0   0   0  1.0   .
1.0 1.0      0.0   0.0   0   0  1.0   .
1.0 2.0      0.0   0.0   0   0  1.0   .
1.0 6.0      0.0   0.0   0   0  1.0   .
1.0 24.0     0.0   0.0   0   0  1.0   .
1.0 36.0     0.0   0.0   0   0  1.0   .
1.0 72.0     0.0   0.0   1   1  0.0   3
1.0 120.0   70.0   0.0   0   0  1.0   .
2.0 0.0      0.0   0.0   0   0  1.0   .
2.0 0.5      0.0   0.0   0   0  1.0   .
2.0 1.0      0.0   0.0   0   0  1.0   .
2.0 2.0      0.0   0.0   0   0  1.0   .
2.0 6.0      0.0   0.0   0   0  1.0   .
2.0 24.0     0.0   0.0   0   0  1.0   .
2.0 36.0     0.0   0.0   0   0  1.0   .
2.0 72.0     0.0   0.0   0   0  1.0   .
2.0 120.0    0.0   0.0   0   0  1.0   .

data of subject 1 will be replicated 2 times within NONMEM, and data of subject 2 will be replicated 3 times. The ID values of the replicates will be 1.00, 1.01, 2.0, 2.01, 2.02.

You may use the $DATA REPL option along with the REPL_ data item such as:

$INPUT ID TIME AMT RATE EVID MDV DV REPL_
$DATA warfarin.dat ignore=C REPL=100

which will result in 200 replications for subject 1, and 300 replications for subject 2. The order in which they appear will be as follows. Two replicates of subject 1 followed by 3 replicates of subject 2, and this pattern is replicated 100 times. If one subject type takes much longer than another to compute during estimation, this pattern allows the best load balancing for parallelization.

Of course, the DV patterns will be identically replicated as well, so replicated data templates make sense only if you will be using $SIML or $DESIGN to subsequently create the unique DV patterns for each replicated subject.

25 PRED_IGNORE_DATA Feature (NM75)

The $DATA IGNORE=(list) and ACCEPT=(list) provide a limited means of filtering the input data set, which is performed by NMTRAN. To provide more elaborate filtering for excluding data, PRED can instruct NONMEM to filter out additional data records at the beginning of the run or problem.

This is done by creating a PRED_IGNORE_DATA_TEST==1 IF block presented in $INFN, $PK, or $PRED. For eample:

$INFN
IF(PRED_IGNORE_DATA_TEST==1) THEN
 PRED_IGNORE_DATA=0
 IF(AGE>35.0) PRED_IGNORE_DATA=1
 IF( ID>10.AND.ID<18.OR.ID>60.AND.ID<70 ) PRED_IGNORE_DATA=1
 RETURN ;Assures no additional code in INFN is executed (saves time)
ENDIF

Or:

$PRED
IF(PRED_IGNORE_DATA_TEST==1) THEN
PRED_IGNORE_DATA=0
 IF(AGE>35.0) PRED_IGNORE_DATA=1
 IF( ID>10.AND.ID<18.OR.ID>60.AND.ID<70 ) PRED_IGNORE_DATA=1
RETURN ;Assures no additional code in PRED is executed (saves time)
ENDIF
...

If PRED_IGNORE_DATA is set to a non-zero value, then the data record is ignored, and excluded from the internal data set. This allows the user to use more complex, multi-line and FORTRAN syntax based, logical operations on data record exclusions.

When PRED_IGNORE_DATA_TEST=1, then ICALL is set to -1. The following variables have properly defined values during this call:

NEWIND, NEWL2, IPROB, NPROB, S1NUM, S2NUM, S1NIT, S2NIT, S1IT, S2IT

So, it is possible to restrict PRED_IGNORE_DATA actions to a particular problem number:

IF(IPROB==2.AND.PRED_IGNORE_DATA_TEST==1) THEN
 PRED_IGNORE_DATA=0
 IF(AGE>35.0) PRED_IGNORE_DATA=1
 IF( ID>10.AND.ID<18.OR.ID>60.AND.ID<70 ) PRED_IGNORE_DATA=1
 RETURN
ENDIF

No other variables are properly defined during PRED_IGNORE_DATA_TEST=1, such as THETAS, data record information such as NIREC, NDREC, etc., and no calls to complicated functions that such as RANDOM() will be valid (simple functions, such as built-in FORTRAN functions, are fine). Furthermore, changes to data items may not be made during this call. Any other functions of $INFN, such as data modification, RANDOM() calls, etc., should be made with separate ICALL==0 or ICALL==1 blocks.

If the user write his own INFN routine in which PRED_IGNORE_DATA code is constructed, then NONMEM needs to be informed with the PRED_IGNORE_DATA option in $DATA. For example:

$PROB THEOPHYLLINE POPULATION DATA

$INPUT          ID DOSE=AMT TIME CP=DV WT

$DATA           THEOPP PRED_IGNORE_DATA

$SUBROUTINES ADVAN2 INFN=myinfn.f90

myinfn.f90:

SUBROUTINE INFN(ICALL,THETA,DATREC,INDXS,NEWIND)
USE SIZES,  ONLY: DPSIZE,ISIZE
USE NMPRD_INT, ONLY: PRED_IGNORE_DATA,PRED_IGNORE_DATA_TEST
INTEGER(KIND=ISIZE) :: ICALL,INDXS,NEWIND
REAL(KIND=DPSIZE) :: THETA
REAL(KIND=DPSIZE) :: DATREC
DIMENSION :: THETA(*),DATREC(*),INDXS(*)
IF(PRED_IGNORE_DATA_TEST== 1)THEN
IF (DATREC(3)>3) THEN
PRED_IGNORE_DATA=1
ENDIF
ENDIF
RETURN
END

If PRED_IGNORE_DATA_TEST and PRED_IGNORE_DATA are used only in verbatim code, it is also necessary to code the PRED_IGNORE_DATA option in $DATA.

26 $DATA CREATES FILE FDATA.csv (NM75)

An additional file, FDATA.csv is produced that outputs the contents of its input data file (typically FDATA) in a comma delimited file format, so you can check how NONMEM interprets the input data. The records in FDATA.csv may differ from those in FDATA in the following cases. If REPL/REPL_ is used, the replicated form of the data will appear in FDATA.csv. Also, records excluded by PRED_IGNORE_DATA will not be present in FDATA.csv. The creation of FDATA.csv can cause a long period of data file loading and processing at the beginning of a run, if the FDATA file is very large (such as >1 MB). As of nm760, the creation of this file can be prevented by adding the option NOFDATACSV on the $DATA record.