Appendix
Appendix I. NM-TRAN Control Records
Listed are some of the options available for some of the most-used NMTRAN records. Guide VIII has the complete list of records and description of options.
$SIZES
$SUPERPROBLEM
$PROBLEM text
$INPUT item₁ item₂ item₃ · · ·
$INDEX [label₁|value₁] [label₂|value₂] [label₃|value₃] ...
$CONTR DATA= ([label₁|0] [label₂|0] [label₃|0])
$DATA [filename|*] [(format)] [IGNORE=c₁] [NULL=c₂] [NOWIDE|WIDE] [CHECKOUT]
[RECORDS=n₁] [LRECL=n₂] [NOREWIND|REWIND]
$SUBROUTINES [subname₁ = name₁] [subname₂ = name₂] ...
[SUBROUTINES=kind]
$ABBREVIATED [COMRES=n₁] [COMSAV=n₂] [DERIV2=NO] [DERIV2=NOCOMMON]
$PRED
the abbreviated code
$THETA value₁ [value₂] [value₃] ...
[NUMBERPOINTS=n] [ABORT|NOABORT]
$OMEGA [DIAGONAL(n)|BLOCK(n)|BLOCK(n) SAME|BLOCK SAME]
[[value₁] [value₂] [value₃] ... [FIXED]]
$SIGMA [DIAGONAL(n)|BLOCK(n)|BLOCK(n) SAME|BLOCK SAME]
[[value₁] [value₂] [value₃] ... [FIXED]]
$MSFI filename [NORESCALE|RESCALE] [NPOPETAS=n]
$SIMULATION (seed1 [seed2] [NORMAL|UNIFORM] [NEW]) ...
[SUBPROBLEMS=n] [ONLYSIMULATION] [OMITTED]
$ESTIMATION [METHOD=kind] [NOINTERACTION|INTERACTION] [NOLAPLACIAN|LAPLACIAN]
[NOPOSTHOC|POSTHOC] [SIGDIGITS=n₁] [MAXEVALS=n₂] [PRINT=n₃]
[ABORT|NOABORT] [MSFO=filename] [NOREPEAT|REPEAT] [OMITTED]
$COVARIANCE [SPECIAL] [MATRIX=c] [PRINT=[E][R][S]]
[CONDITIONAL|UNCONDITIONAL] [OMITTED]
$TABLE [list1] [BY list2] [PRINT|NOPRINT] [FILE=filename] [NOHEADER|ONEHEADER]
[UNCONDITIONAL|CONDITIONAL] [OMITTED]
$SCATTERPLOT list1 VS list2 [BY list3]
[UNIT] [ORD0] [FROM n₁] [TO n₂]
[UNCONDITIONAL|CONDITIONAL] [OMITTED]
$INCLUDE filename [n]
Appendix II. NM-TRAN Data Set – Example
Here is a NM-TRAN data set which NM-TRAN translates into a NONMEM data set shown in Appendix III. The NONMEM data set in Appendix III is identical to that shown in Figure 75 of NONMEM Users Guide, Part I, except for spacing between fields. This NM-TRAN data set is recorded on the NONMEM distribution medium as file THEO; see Guide III.
1 4.02 0. .74 79.6
1 . 0.25 2.84 .
1 . 0.57 6.57 .
1 . 1.12 10.5 .
1 . 2.02 9.66 .
1 . 3.82 8.58 .
1 . 5.1 8.36 .
1 . 7.03 7.47 .
1 . 9.05 6.89 .
1 . 12.12 5.94 .
1 . 24.37 3.28 .
2 4.4 0. 0. 72.4
2 . .27 1.72 .
2 . .52 7.91 .
2 . 1. 8.31 .
2 . 1.92 8.33 .
2 . 3.5 6.85 .
2 . 5.02 6.08 .
2 . 7.03 5.4 .
2 . 9. 4.55 .
2 . 12. 3.01 .
2 . 24.3 .90 .
The data set continues with data for subjects 3-12 (see the original PDF for the complete data set). The columns are ID, DOSE, TIME, CP, and WT (weight).
Appendix III. NM-TRAN Outputs – Example
The NM-TRAN outputs obtained from using the NM-TRAN control stream listed in chapter I, along with the NM-TRAN data set listed in Appendix II, are described in this appendix. Some code that is extraneous to the control stream was removed from SUBROUTINE PRED for the purposes of simplicity.
Data Set - FDATA
The NONMEM data set is substantially similar to the NM-TRAN data set, but with a standardized format. The subjects 1-12 appear in sequence with their respective dose and observation records.
Control Stream - FCON
FILE FSTREAM
PROB THEOPHYLLINE POPULATION DATA
FMTN 3
LDFO 0
DATA 1 0 132 5 0 0 0 0 -1 0 0
ITEM 1 4 0 0 1 0 0 0 0 0 0 0 0 0 0 0
XVID 0 0 0 0 0
MSDT 0.00000000000000E+000
LABL ID, DOSE
TIME, CP
WT
LBW1 IWRS,IPRD
IRS,NPRED
NRES,NWRES
NIWRES,NIPRED
NIRES,CPRED
CRES,CWRES
CIWRES,CIPRED
CIRES,PREDI
RESI,WRESI
IWRESI,IPREDI
IRESI,CPREDI
CRESI,CWRESI
CIWRESI,CIPREDI
CIRESI,EPRED
ERES,EWRES
EIWRES,EIPRED
EIRES,NPDE
ECWRES,NPD
OBJI
LRES SIGMA
LTHT
LETA
LEPS
FORM
(5E6.0)
STRC 3 3 1 0 0 0 1 1 0
STRC 1 3
THCN 1 0 0 0
THTA 3.000000000000000E+00, 8.000000000000000E-02, 4.000000000000000E-02
THTU 0,0,0
LOWR 1.000000000000000E-01, 8.000000000000000E-03, 4.000000000000000E-03
UPPR 5.000000000000000E+00, 5.000000000000000E-01, 9.000000000000000E-01
BLST 6.000000000000000E+00, 5.000000000000000E-03, 3.000000000000000E-01
2.000000000000000E-04, 6.000000000000000E-03, 4.000000000000000E-01
DIAG 4.000000000000000E-01
DFLT -1
ESTM 0 450 3 5 0 0 0 0 0 0 0 0 0 0 0 0 0
0 0 0 0 -1 -1 0 0 0
(... BEST vector, COVR, TABL, SCAT records follow ...)
File Stream - FSTREAM
DATA FDATA
****
Report - FREPORT
NM-TRAN VERSION 7.6.0
GENERATED DP SUBROUTINES:
PRED
NONMEM SUBROUTINES: ALL
Generated Subroutine - FSUBS (PRED)
SUBROUTINE PRED (ICALL,NEWIND,THETA,DATREC,INDXS,F,G,H)
USE NMPRD4P
USE SIZES, ONLY: DPSIZE,ISIZE
USE PRDIMS, ONLY: GPRD,HPRD,GERD,HERD,GPKD
USE NMBAYES_REAL, ONLY: PRIOR_INFO
USE NM_BAYES_INT, ONLY: TOLTOPRED
USE NMPRD_INT, ONLY: PRED_IGNORE_DATA,PRED_IGNORE_DATA_TEST
USE NMPRD_REAL,ONLY: ETA,EPS
USE NMPRD_INT, ONLY: MSEC=>ISECDER,MFIRST=>IFRSTDER,IFIRSTEM
USE NMPRD_INT, ONLY: MDVRES,ETASXI,NPDE_MODE,NOFIRSTDERCODE
USE NMPRD_REAL, ONLY: DV_LOQ,CDF_L,DV_LAQ,CDF_LA
USE NMPRD_INT, ONLY: NEWL2
USE NMBAYES_REAL, ONLY: LDF
USE NMBAYES_INT, ONLY: FLDF
IMPLICIT REAL(KIND=DPSIZE) (A-Z)
REAL(KIND=DPSIZE) :: DATREC
SAVE
INTEGER(KIND=ISIZE) :: ICALL,NEWIND,INDXS
REAL(KIND=DPSIZE) :: G(GPRD,*),H(HPRD,*)
DIMENSION :: THETA(*),DATREC(*),INDXS(*)
INTEGER(KIND=ISIZE) :: FIRSTEM
IF(ICALL==0.AND.TOLTOPRED==1) RETURN
FIRSTEM=IFIRSTEM
IF (ICALL <= 1) CALL ASSOCNMPRD4
IF (ICALL == 4) THEN
IF (NEWIND /= 2) THEN
CALL SIMETA(ETA)
IF (IQUIT == 1) RETURN
ENDIF
IF (NEWL2 == 1) THEN
CALL SIMEPS(EPS)
IF (IQUIT == 1) RETURN
ENDIF
ELSE
IF (NEWIND /= 2) THEN
CALL GETETA(ETA)
IF (IQUIT == 1) RETURN
EPS(001)=0.D0
ENDIF
ENDIF
DOSE=DATREC(002)
TIME=DATREC(003)
WT=DATREC(005)
IF(DOSE /= 0.D0)THEN
DS=DOSE*WT
W=WT
ENDIF
KA=THETA(001)+ETA(001)
KE=THETA(002)+ETA(002)
CL=THETA(003)*W+ETA(003)
B000005=-KE*TIME
B000006=-KA*TIME
B000007=DEXP(B000005)
B000008=DEXP(B000006)
D=B000007-B000008
B000009=KA-KE
E=CL*B000009
F=DS*KE*KA/E*D
Y=F+EPS(001)
C000031=1.D0
IF (FIRSTEM == 1) THEN !1
A000034=-TIME
A000035=-TIME
A000036=B000007*A000034
A000037=B000008*A000035
A000039=-A000037
A000041=-1.D0
A000043=CL*A000041
B000011=DS*KA/E*D
B000012=DS*KE/E*D
B000013=-DS*KE*KA/E/E*D
A000048=B000013*CL+B000012
A000049=B000013*A000043+B000011
A000050=B000013*B000009
B000014=DS*KE*KA/E
A000051=B000014*A000039+A000048
A000052=B000014*A000036+A000049
A000060=A000052
A000061=A000051
A000062=A000050
G(001,1)=A000061
G(002,1)=A000060
G(003,1)=A000062
ENDIF !1
H(001,1)=C000031
IF (FIRSTEM == 1) THEN !2
ENDIF !2
F=Y
RETURN
ENDAppendix IV. Another Example
Figures 1 and 2 of NONMEM Users Guide, Part I, show a PRED routine and a NONMEM control stream (with embedded data), respectively. The NONMEM outputs resulting from Figures 1 and 2 are shown in Figures 3-18 of Part I. NM-TRAN inputs and outputs are given below. The inputs correspond to Figures 1 and 2. The NONMEM outputs resulting from the NM-TRAN outputs and corresponding to those shown in Figures 4-18 are exactly the same as those shown in Figures 4-18. The NONMEM output corresponding to that shown in Figures 3a-b, the problem summary, is a little different (in part because NM-TRAN generates ID data items).
NM-TRAN Data Set
320 .27 1.71
320 .52 7.91
320 1. 8.31
320 1.92 8.33
320 3.5 6.85
320 5.02 6.08
320 7.03 5.4
320 9. 4.55
320 12. 3.01
320 24.3 .90
NM-TRAN Control Stream
$PROB SIMPLE NONLINEAR REGRESSION OF CP VS TIME DATA FROM ONE SUBJECT
$INPUT DOSE TIME CP=DV
$DATA DATA
$PRED
;THETA(1)=ABSORPTION RATE CONSTANT (1/HR)
;THETA(2)=ELIMINATION RATE CONSTANT (1/HR)
;THETA(3)=VOLUME OF DISTRIBUTION (LITERS)
D=EXP(-THETA(2)*TIME)-EXP(-THETA(1)*TIME)
E=THETA(3)*(THETA(1)-THETA(2))
F=DOSE*THETA(1)/E*D
Y=F+ETA(1)
$THETA (.4,1.7,7.) (.025,.102,.4) (10,29,80)
$EST MAXEVAL=240 SIGDIGITS=4 PRINT=2
$COV
$TABLE TIME
$SCAT (CP PRED RES) VS TIME
$SCAT PRED VS CP UNITNONMEM Data Set - FDATA
NONMEM data records include the generated .ID. column (values alternating 1 and 2):
320 .27 1.71 1
320 .52 7.91 2
320 1. 8.31 1
320 1.92 8.33 2
320 3.5 6.85 1
320 5.02 6.08 2
320 7.03 5.4 1
320 9. 4.55 2
320 12. 3.01 1
320 24.3 .90 2
Appendix V. NM-TRAN Control Records with PREDPP
$PROBLEM text
$INPUT item₁ item₂ item₃ · · ·
$BIND value₁ value₂ ... valueₙ
$INDEX [label₁|value₁] [label₂|value₂] [label₃|value₃] ...
$CONTR DATA= ([label₁|0] [label₂|0] [label₃|0])
$DATA [filename|*] [(format)] [IGNORE=c₁] [NULL=c₂] [NOWIDE|WIDE] [CHECKOUT]
[RECORDS=n₁] [LRECL=n₂] [NOREWIND|REWIND]
$SUBROUTINES [subname₁ = name₁] [subname₂ = name₂] ...
[SUBROUTINES=kind] [TOL=n₁]
$MODEL [NCOMPARTMENTS=n₁] [NEQUILIBRIUM=n₂] [NPARAMETERS=n₃]
[COMPARTMENT=([name] [attribute₁] [attribute₂] ...)] ...
[LINK compnameₐ [TO|AND] compnameᵦ BY k [l]] ...
$ABBREVIATED [COMRES=n₁] [COMSAV=n₂] [DERIV2=NO] [DERIV2=NOCOMMON]
$PK
abbreviated code
$ERROR
abbreviated code
$DES
abbreviated code
$AESINITIAL
abbreviated code
$AES
abbreviated code
$TOL
abbreviated code
$THETA value₁ [value₂] [value₃] ...
[NUMBERPOINTS=n] [ABORT|NOABORT]
$OMEGA [DIAGONAL(n)|BLOCK(n)|BLOCK(n) SAME|BLOCK SAME]
[[value₁] [value₂] [value₃] ... [FIXED]]
$SIGMA [DIAGONAL(n)|BLOCK(n)|BLOCK(n) SAME|BLOCK SAME]
[[value₁] [value₂] [value₃] ... [FIXED]]
$MSFI filename [NORESCALE|RESCALE] [NPOPETAS=n]
$SIMULATION (seed1 [seed2] [NORMAL|UNIFORM] [NEW]) ...
[SUBPROBLEMS=n] [ONLYSIMULATION] [OMITTED]
$ESTIMATION [METHOD=kind] [NOINTERACTION|INTERACTION] [NOLAPLACIAN|LAPLACIAN]
[NOPOSTHOC|POSTHOC] [SIGDIGITS=n₁] [MAXEVALS=n₂] [PRINT=n₃]
[ABORT|NOABORT] [MSFO=filename] [NOREPEAT|REPEAT] [OMITTED]
$COVARIANCE [SPECIAL] [MATRIX=c] [PRINT=[E][R][S]]
[CONDITIONAL|UNCONDITIONAL] [OMITTED]
$TABLE [list1] [BY list2] [PRINT|NOPRINT] [FILE=filename] [NOHEADER|ONEHEADER]
[UNCONDITIONAL|CONDITIONAL] [OMITTED]
$SCATTERPLOT list1 VS list2 [BY list3]
[UNIT] [ORD0] [FROM n₁] [TO n₂]
[UNCONDITIONAL|CONDITIONAL] [OMITTED]
Appendix VI. NM-TRAN Data Set with PREDPP – Example
Here is a NM-TRAN data set which NM-TRAN translates into a NONMEM data set shown in Appendix VII. The NONMEM data set in Appendix VII is identical to that shown in Appendix II of NONMEM Users Guide, Part VI, except for spacing between columns. This NM-TRAN data set is recorded on the NONMEM distribution medium; see Guide III.
For each subject, the first row has dose amount and body weight; subsequent rows have time and concentration observations:
1 4.02 0. . 79.6
1 . 0. .74 .
1 . 0.25 2.84 .
1 . 0.57 6.57 .
1 . 1.12 10.5 .
1 . 2.02 9.66 .
1 . 3.82 8.58 .
1 . 5.1 8.36 .
1 . 7.03 7.47 .
1 . 9.05 6.89 .
1 . 12.12 5.94 .
1 . 24.37 3.28 .
2 4.4 0. . 72.4
2 . 0. 0. .
2 . .27 1.72 .
...
The data set continues with data for subjects 2-12. The columns are ID, DOSE (AMT), TIME, CP (DV), and WT.
Appendix VII. NM-TRAN Outputs with PREDPP – Example
The NM-TRAN outputs obtained from using the NM-TRAN control stream listed in chapter V, along with the NM-TRAN data set listed in Appendix VI, are given below.
Data Set - FDATA
NONMEM data records include EVID and MDV columns. For example:
1 4.02 0. 79.6 1 1
1 0. .74 0 0
1 0.25 2.84 0 0
1 0.57 6.57 0 0
...
Report - FREPORT
NM-TRAN VERSION 7.6.0
SUBROUTINES FROM THE PREDPP LIBRARY:
PRED PREDI CHECK SADVAN ADVAN2 SSS0 TRANS1 INFN
GENERATED DP SUBROUTINES:
PK ERROR
NONMEM SUBROUTINES: ALL
Generated Subroutines - FSUBS
Generated PK subroutine (excerpt):
SUBROUTINE PK(ICALL,IDEF,THETA,IREV,EVTREC,NVNT,INDXS,IRGG,GG,NETAS)
USE NMPRD4P
USE SIZES, ONLY: DPSIZE,ISIZE
USE PRDIMS, ONLY: GPRD,HPRD,GERD,HERD,GPKD
USE NMBAYES_REAL, ONLY: PRIOR_INFO
USE NMBAYES_REAL, ONLY: ADDL_ACTUAL,ADDL_TIMEDIFF,ADDL_TIME
USE NMPRD_INT, ONLY: PRED_IGNORE_DATA,PRED_IGNORE_DATA_TEST
USE PRCOM_INT, ONLY: DES_DER=>MITER
USE NMPRD_REAL,ONLY: ETA,EPS
USE NMPRD_INT, ONLY: MSEC=>ISECDER,MFIRST=>IFRSTDER,COMACT,COMSAV,IFIRSTEM,FIRSTEM
...
IMPLICIT REAL(KIND=DPSIZE) (A-Z)
REAL(KIND=DPSIZE) :: EVTREC
SAVE
INTEGER(KIND=ISIZE) :: ICALL,IDEF,IREV,NVNT,INDXS,IRGG,NETAS
DIMENSION :: IDEF(7,*),THETA(*),EVTREC(IREV,*),INDXS(*),GG(IRGG,GPKD+1,*)
FIRSTEM=IFIRSTEM
IF (ICALL <= 1) THEN
CALL ASSOCNMPRD4
IDEF(1,0001) = -9
IDEF(1,0002) = 1
IDEF(1,0003) = 0
IDEF(1,0004) = 0
IDEF(2,0003) = 0
IDEF(2,0004) = 0
IDEF(3,0002) = 4
CALL GETETA(ETA)
IF (IQUIT == 1) RETURN
RETURN
ENDIF
IF (NEWIND /= 2) THEN
IF (ICALL == 4) THEN
CALL SIMETA(ETA)
ELSE
CALL GETETA(ETA)
ENDIF
IF (IQUIT == 1) RETURN
ENDIF
WT=EVTREC(NVNT,005)
KA=THETA(001)+ETA(001)
K=THETA(002)+ETA(002)
CL=THETA(003)*WT+ETA(003)
SC=CL/K/WT
IF (FIRSTEM == 1) THEN
A000031=1.D0
A000032=1.D0
B000001=1.D0/K/WT
A000034=B000001
B000002=-CL/K/K/WT
A000035=B000002*A000032
GG(0001,1,1)=K
GG(0001,0003,1)=A000032
GG(0003,1,1)=KA
GG(0003,0002,1)=A000031
GG(0004,1,1)=SC
GG(0004,0003,1)=A000035
GG(0004,0004,1)=A000034
ELSE
GG(0001,1,1)=K
GG(0003,1,1)=KA
GG(0004,1,1)=SC
ENDIF
RETURN
ENDGenerated ERROR subroutine (excerpt):
SUBROUTINE ERROR (ICALL,IDEF,THETA,IREV,EVTREC,NVNT,INDXS,F,G,HH)
USE NMPRD4P
USE SIZES, ONLY: DPSIZE,ISIZE
...
IF (ICALL <= 1) THEN
CALL ASSOCNMPRD4
IDEF(2)=2
HH(1,1)=1.0D0
IDEF(3)=000
RETURN
ENDIF
IF (ICALL == 4) THEN
IF (NEWL2 == 1) THEN
CALL SIMEPS(EPS)
IF (IQUIT == 1) RETURN
ENDIF
ENDIF
Y=F+EPS(001)
IF (FIRSTEM == 1) THEN !1
ENDIF !1
F=Y
RETURN
ENDAppendix VIII. Additional NM-TRAN Control Streams
The NM-TRAN control stream listed in chapter V specifies that ADVAN2 be used. The results from NONMEM-PREDPP, using this control stream along with the NM-TRAN data set listed in Appendix VI, can be essentially duplicated, using NM-TRAN control streams which specify different ADVAN’s, but which name the same data set. Two such control streams are given here, one specifying ADVAN7 and the other specifying ADVAN6. The two control streams are recorded on the NONMEM distribution medium; see Guide III.
NM-TRAN Control Stream Specifying ADVAN7
$PROB THEOPHYLLINE POPULATION DATA
$INPUT ID DOSE=AMT TIME CP=DV WT
$DATA THEOPP
$SUBROUTINES ADVAN7
$MODEL COMP=(DEPOT,INITIALOFF,DEFDOSE) COMP=(CENTRAL,DEFOBS,NOOFF)
$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
CALLFL=1
K12=THETA(1)+ETA(1)
K20=THETA(2)+ETA(2)
CL=THETA(3)*WT+ETA(3)
S2=CL/K20/WT
$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
$EST MAXEVAL=450 PRINT=5
$COV
$TABLE ID DOSE WT TIME
$SCAT (RES WRES) VS TIME BY IDNM-TRAN Control Stream Specifying ADVAN6
$PROB THEOPHYLLINE POPULATION DATA
$INPUT ID DOSE=AMT TIME CP=DV WT
$DATA THEOPP
$SUBROUTINES ADVAN6 TOL=5
$MODEL COMP=(DEPOT,INITIALOFF,DEFDOSE) COMP=(CENTRAL,DEFOBS,NOOFF)
$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
CALLFL=1
KA=THETA(1)+ETA(1)
KE=THETA(2)+ETA(2)
CL=THETA(3)*WT+ETA(3)
S2=CL/KE/WT
$THETA (.1,3,5) (.008,.08,.5) (.004,.04,.9)
$OMEGA BLOCK(3) 6 .005 .0002 .3 .006 .4
$DES
DADT(1)=-KA*A(1)
DADT(2)= KA*A(1)-KE*A(2)
$ERROR
Y=F+EPS(1)
$SIGMA .4
$EST MAXEVAL=450 PRINT=5
$COV
$TABLE ID DOSE WT TIME
$SCAT (RES WRES) VS TIME BY IDAppendix IX. Another Example with PREDPP
Figures 7, 11, and 25 of NONMEM Users Guide, Part VI, show a PK routine, an ERROR routine and a NONMEM control stream (with embedded data), respectively. Problem summary pages from NONMEM and PREDPP, resulting from Figures 7, 11, and 25 are shown in Figures 27-28 of Part VI. NM-TRAN inputs and outputs correspond to Figures 7, 11, and 25. The resulting problem summary page from NONMEM is just a little different from that shown in Figure 27 of Part VI due to the fact that NM-TRAN generates EVID, MDV and ID data items. The NM-TRAN data set and control stream are recorded on the NONMEM distribution medium; see Guide III.