___________________________________________________________________
| |
| ABBREVIATED CODE |
|_________________________________________________________________|
MEANING: FORTRAN-like statements
CONTEXT: Abbreviated code
SAMPLE:
$PK CL=THETA(1)+ETA(1)
DISCUSSION:
Abbreviated code is FORTRAN-like language within an NM-TRAN control
stream that is used to specify a model. The $PRED, $PK, $ERROR, $DES,
$AES, $AESINITIAL, $TOL, $MIX, and $INFN records each begin a block of
abbreviated code. Such a block ends with either the appearance of
another record beginning with a "$", or with the absence of any
further records in the control stream.
The general rules are:
One statement of abbreviated per line, starting anywhere on the line.
No continuation lines.
No statement numbers (unlike with FORTRAN).
Comments may be included on any line after the semicolon character ";".
No statement types other than assignment,
IF, ELSE, ELSEIF, ENDIF, DO WHILE,
ENDDO, CALL, WRITE, PRINT, RETURN, OPEN, CLOSE, REWIND.
(e.g., no GOTO, READ, FORMAT.)
A special statement type, EXIT, is permitted.
ASSIGNMENT STATEMENTS
An assignment statement (A=B) uses right-hand quantities in an
expression B in order to define a quantity A.
Permissible right-hand quantities are:
previously defined quantities
constants, e.g 1, 1.1, 3E+1 3E1, 3E01, 3E-1 3E-01, 3D+1, 3D1, 3D01,
3D-1 3D-01
THETA, OMEGA and SIGMA elements, e.g. THETA(1), OMEGA(2,2). When
the two subscripts for an OMEGA or SIGMA element are the same, only
one subscript is needed, e.g. OMEGA(2).
labels of data items defined in the $INPUT record
variables ETA(n), EPS(n), ERR(n), which are understood to have mean
0 and variances and covariances given by elements of the OMEGA and
SIGMA arrays.
operators + - * / **
parentheses ()
built-in functions: LOG (natural log), LOG10, EXP,
SQRT, SIN, COS, ABS, TAN, ASIN, ACOS, ATAN, ABS, INT, PHI. |
abbreviated functions (see below) |
Further information about Assignment statements:
Where subscripts are permitted or are necessary, they must be posi-
tive integer constants, e.g., THETA(1).
Parentheses may be nested in the right-hand side of an assignment
statement.
Except in certain blocks of abbreviated code (i.e. a simulation
block, an initialization block, or a finalization block), the vari-
ables ETA(n), EPS(n), ERR(n) are considered to be (the base) random
variables, and quantities defined in terms of these variables
(directly or indirectly) are themselves considered to be random
variables. NM-TRAN sets up computations for derivatives of random
variables with respect to the base random variables.
Left-hand quantities VECTRA(n), VECTRB(n), VECTRC(n) may be defined,
and these become elements of vectors VECTRA, VECTRB, VECTRC. If VEC-
TRA, VECTRB, VECTRC is defined without a subscript, it is understood
to be a simple variable. Whereas once it is defined, a vector ele-
ment may be used as a right-hand quantity - in the same way as any
previously defined variable, a vector itself may be used only as an
argument to an abbreviated function. (See VECTORS and ABBREVIATED
FUNCTIONS, below.)
Values may be assigned to certain special variables: RPTO, RPTON and
PRDFL - with the repetition feature (See NMPR10); SKIP_ (but only in
a finalization block) - with superproblems or subproblems (See
NMPR15).
Variables, constants, and functions are all of single or double pre-
cision floating point type. The precision (double or single) is
specified with the $SUBROUTINES record. (E.g., K=.5 gives K the
value .5, not 0 as it would be under the FORTRAN convention that K
is integer type.)
Except in certain blocks of abbreviated code (i.e. a simulation
block, an initialization block, or a finalization block), a label in
an $INPUT record may not appear on the left in an assignment state-
ment.
There is a reserved storage area of common NMPRD4, and when defining
the kth variable in this area, it may be referenced as COM(k).
Then, even if the variable is defined in terms of random variables,
it is not regarded as being a random variable; derivatives of COM(k)
with respect to the base random variables are not computed.
CONDITIONAL STATEMENTS
Conditional statements have one of two forms:
IF (condition) assignment statement
IF (condition) THEN
abbreviated code ...
ELSEIF (condition) THEN
abbreviated code ...
ELSE
abbreviated code ...
ENDIF
See below for a restriction on ELSEIF.
Conditions may include the operators .EQ., .LE., .GE., .LT., .GT.,
.AND., and .OR.. They may include expressions that can be used as
right-hand quantities with assignment statements. They may not
include parentheses except in such expressions.
Valid: IF (Q.EQ.(R+C)/D) ...
Invalid: IF (Q.EQ.R.AND.(C.GT.D.OR.E.EQ.F)) ...
With $PRED, $PK, and $ERROR records, a condition may test the ICALL
argument. However, if the test is IF (ICALL.EQ.2), then ELSE may
not be used. Special rules apply. For more detail, see SPECIAL
STATEMENTS (below), and help entries for these records.
A condition may also test certain variables defined in commons
(See Variables_in_commons, NONMEM_commons, PREDPP_commons).
Abbreviated code in a particular THEN or ELSE" clause may not con-
tain multiple definitions of the same random variable. The code
below is invalid:
IF (condition) THEN
X=...an expression involving a random variable
X= ....
ENDIF
Random variables cannot be defined within nested conditionals, i.e.,
within a conditional structure beginning with an IF and containing
another IF. The use of ELSEIF ... THEN implies a nested condi-
tional.
A special rule applies when random variables are defined via condi-
tional statements. If a random variable is multiply defined within
a series of IF ... THEN structures, but all conditions are false,
then the value of the random variable is set to zero. If an ELSE
appears, then not all conditions are false.
Consider two cases in which the following statements are the only
ones defining TVK and K, respectively:
IF (WT.GT.0) TVK=THETA(1)*WT
If the condition is false, the non-random variable TVK retains the
value set with the previous data record.
IF (WT.GT.0) K=THETA(1)*WT*EXP(ETA(1))
If the condition is false, the value of the random variable K is set
to zero.
NM-TRAN prints a warning message when it detects such code. In $PK,
$ERROR, and $PRED records, recursion code may be used in an explicit
manner, so that with:
IF (WT.GT.0) THEN
K=THETA(1)*WT*EXP(ETA(1))
ELSE
K=K
ENDIF
if the condition is false, K retains its value set with the previous
data record.
Recursion code can be used in $PRED, $PK, and $ERROR records for
other purposes as well. The following two fragments of code illus-
trate how one can use abbreviated code to implement recursive kinet-
ics in $PRED. The first example works with a single bolus dose and
the second example works with single or multiple bolus doses. Simi-
lar code can be used in $PK and $ERROR.
K=THETA(1)*EXP(ETA(1))
IF (TIME.EQ.0) THEN
OLDA=AMT
T=TIME
ENDIF
A=OLDA*EXP(-K*(TIME-T))
OLDA=A
T=TIME
K=THETA(1)*EXP(ETA(1))
IF (TIME.EQ.0) THEN
A=AMT
T=TIME
ELSE
A=A*EXP(-K*(TIME-T))+AMT
ENDIF
T=TIME
EXIT STATEMENT
The exit statement has three forms:
EXIT
EXIT n
EXIT n k
n is called the "PRED error return code"; (also called the "PRED
exit code.") It must be 1 or 2. Default is 1.
k is the user error code. It may be omitted; if present, it must be
integer-valued in the range 0-999. Default is 0.
The EXIT statement causes an immediate exit from the routine and, if
PREDPP is being used, a subsequent immediate exit from PREDPP, with
a return to NONMEM. It is typically used in an IF statement to
avoid further computation of the users code when the values of
theta/eta's set by NONMEM are inappropriate or would lead to an
arithmetic exception. If such an exit occurs during a Simulation,
Covariance, Table or Scatterplot Step, or during computation of the
initial value of the objective function, NONMEM will abort. If the
exit occurs during an Estimation or Initial Estimates Step, NONMEM's
action depends on the error return code value:
1 Suppose first that a search for eta is not underway. Then a
search for theta is underway, and when a search is underway for
theta, the following happens:
If the NOABORT option is used, NONMEM will try to continue
using different values for theta (i.e. "theta-recovery");
otherwise, NONMEM aborts. If theta-recovery fails, NONMEM
aborts.
Next, suppose a search for eta is underway. NONMEM will try to
continue using different values for eta (i.e. "eta-recovery").
Suppose eta-recovery fails. If a search for theta is not also
underway, NONMEM aborts. Otherwise, the above procedure
regarding theta-recovery applies. (See also Guide VI, section
III.K).
2 NONMEM aborts immediately.
If NONMEM aborts, and k>0, a user message such as the following is
printed in the output:
"PK SUBROUTINE: USER ERROR CODE = k"
This message is intended to help the user distinguish which EXIT
statement caused NONMEM to abort when more than one EXIT statement
is present in the abbreviated code.
WRITE AND PRINT STATEMENTS
(See write print).
SPECIAL STATEMENTS
Optional. Each of these special statements is permitted in special
blocks of abbreviated code.
(See Initialization-Finalization block, Simulation block).
(See Expectation block, Data_Average block).
CALL PASS(MODE)
Must be coded exactly as shown. May be used only in $PRED
initialization-finalization blocks, and in $INFN records. If
present, MODE becomes a reserved variable with type INTEGER, and may
not be used outside the block(s).
CALL SUPP(ie,ic)
Must be coded as shown, with constant integer values 0 or 1 in place
of ie and ic. A value 1 for ie (ic) suppresses output from the
Estimation (Covariance) step. A value 0 does not suppress the out-
put from the step. May be used only in $PRED initialization-
finalization blocks, and in $INFN records. The ie (ic) value
remains in force until changed by a call to SUPP.
CALL RANDOM(n,R)
Must be coded as shown, with a constant integer value 1-10 in place
of n. The value is the number of the random source. R is a random
number from this source. May be used only in Simulation and Expec-
tation blocks. If present, R becomes a reserved variable with type
REAL, and may not be used outside the block(s).
CALL SIMETA(ETA)
Must be coded exactly as shown. May only be used in Simulation
blocks. Note that NM-TRAN itself provides the minimum necessary
call to SIMETA. This statement is used in abbreviated code only to
obtain a different value of ETA, e.g., so that the eta distribution
may be truncated:
DO WHILE (ETA(1).GT.5)
CALL SIMETA(ETA)
ENDDO
CALL SIMEPS(EPS)
Must be coded exactly as shown. May only be used in Simulation
blocks. Note that NM-TRAN provides the minimum necessary call to
SIMEPS. This statement is used in abbreviated code only to obtain a
different value of EPS, e.g., so that the distribution may be trun-
cated (see SIMETA above).
DO WHILE( condition )
May be used in all special blocks. Marks the beginning of a set of
statements that are executed repeatedly until the condition is
false. The ending of the set of statements is marked by the state-
ment ENDDO. The non-FORTRAN syntax DO WHILE(DATA) is permitted in
$PRED initialization and finalization blocks, and in the $INFN
record.
(See Initialization-Finalization block).
RETURN
May used in all special blocks. RETURN statements must be used with
caution because they by-pass certain normal final actions of the
routine.
VECTORS and ABBREVIATED FUNCTIONS
A vector can have up to 9 elements. Elements can be defined in any
order.
Vectors that are defined outside of $DES (or $AES) may not be used
in the $DES (or $AES) code. I.e., a vector may not be an implicit
basic PK parameter.
If FUNCA, FUNCB, or FUNCC is defined without a subscript, it is
understood to be a simple variable, and then it may appear as such
as a right-hand quantity. If FUNCA, FUNCB, or FUNCC appears for the
first time as a right-hand quantity, it is understood to be an
abbreviated function, and then it must include a single argument,
e.g. FUNCA(THETA(1)). Complete FORTAN code for an abbreviated func-
tion is supplied by the user (See abbreviated function).
The argument of an abbreviated function may be any expression that
can be used in an assignment statement (possibly involving explicit
vector elements), or it can be simply a vector. In the latter case,
any VECTR may be used with any FUNC, e.g. X=FUNCA(VECTRB).
PSEUDO ASSIGNMENT STATEMENTS
Pseudo-assignment statements are optional and provide certain spe-
cial instructions. If present, they must appear (in any order) at
the beginning of a record, before the rest of the essential abbrevi-
ated code comprising that record. They may be enclosed in
parentheses, but two or more pseudo-assignment statements enclosed
by parentheses must be separated by a semicolon ";". The following
pseudo-statement may be used in all records except $MIX.
COMRES=-1 : All quantities defined in abbreviated code are to be
stored locally; they are not to be stored in the (global) COMMON
NMPRD4.
(Variables in COMMON NMPRD4 can be used for communication between
various user-routines, and can be displayed in tables and scatter-
plots.)
See the entries for specific records for information about pseudo-
assignment statements special to those records.
RESERVED VARIABLE NAMES
Reserved variable names include names of those variables that have
special meaning for the user, as well as names of variables that are
used internally by NM-TRAN. Entries for $PRED, $PK, $ERROR, $DES,
$AES, $AESINITIAL, and $TOL describe the reserved variable names for
these abbreviated codes. A variable name that is reserved in an
abbreviated code may not be used as the name of a variable defined
in this code, or in any other abbreviated code unless the pseudo-
assignment statement COMRES=-1 is used (in some code). If a
reserved variable name is inappropriately used, NM-TRAN will gen-
erate an error message.
The following names are reserved in all abbreviated codes for inter-
nal use by NM-TRAN:
Names of commons and of variables in the commons
(See Variables_in_commons).
GETETA SIMETA SIMEPS
COMSAV NWIND ETEXT IERPRD MSEC MFIRST NETEXT
ETA1-ETA9,ETA10-ETA99
Annnnn Bnnnnn Cnnnnn Dnnnnn Ennnnn Fnnnnn Pnnnnn Qnnnnn
MCnnnn MEnnnn MGnnnn MTnnnn
(where nnnnn is numeric 00000-99999, and nnnn is numeric 0000-
9999)
REFERENCES: Guide IV Section IV
REFERENCES: Guide VI Section III.K
Go to main index.
Created by nmhelp2html v. 1.0 written by Niclas Jonsson (Modified by AJB 5/2006,11/2007)