___________________________________________________________________
| |
| $DATA |
|_________________________________________________________________|
MEANING: Describes the NM-TRAN data set
CONTEXT: NM-TRAN Control Record
USAGE:
$DATA [filename|*] [(format)] [IGNORE=c1] [NULL=c2]
[IGNORE=(list)...|ACCEPT=(list)...] |
[NOWIDE|WIDE] [CHECKOUT]
[RECORDS=n1|RECORDS=label] |
[LRECL=n2] [NOREWIND|REWIND]
[NOOPEN] [LAST20=n3] [TRANSLATE=(list)]
SAMPLE:
$DATA DATAFILE
DISCUSSION:
This record specifies the data set to be used. It is required with
the first problem specification. It must precede any other NM-TRAN
control record that refers to specific data item types. May also be
coded $INFILE.
Optional with the second or subsequent problem specifications. If
omitted, NONMEM re-uses the data set from the previous problem (which
will include any modifications made via transgeneration, e.g., via use
of NONMEM's PASS, or via simulation).
OPTIONS:
filename
Name of the file containing the data set. Must be the first
option. If it contains commas, semicolons, or parentheses, then
it must be surrounded by single quotes ' or double quotes ".
Filename may also contain equal signs if it is enclosed in
quotes.
If the file is opened by NM-TRAN, filename may contain embedded |
spaces if it is enclosed in quotes, and may contain at most 80 |
characters. If the file is opened by NONMEM, the filename may |
not contain embedded spaces, and may contain at most 71 charac- |
ters. |
If filename is the same as any option of the $DATA record, it
must be enclosed in quotes.
* may be coded in a problem subsequent to the first. This has
the same effect as omitting the $DATA record (NONMEM is told to
re-use the previous data set), but allows the CHECKOUT option to
be included. With *, no other option may be included.
(format)
FORTRAN format specification to be used to read the data. Format
codes F, E, and X may be used, but not I. When a format is pro-
vided, the label DROP cannot be used on the $INPUT record and
options WIDE and NULL may not be coded. If omitted, NM-TRAN will
generate a suitable FORMAT specification.
RECORDS=n1
The number of records to be read from the NM-TRAN data set.
Comment records are not counted. If NM-TRAN does not drop any |
records from its data set (see IGNORE list and ACCEPT list), then |
n1 is also the number of records written to the NONMEM data set. |
If NM-TRAN drops records, then the total number of records writ- |
ten to the NONMEM data set is n1 minus the number of dropped |
records. If omitted, the records written to the NONMEM data set |
are all the records in the NM-TRAN data set up to the end-of-file |
(or up to a NONMEM FINISH record) minus the number of comment and |
dropped records. |
May also be coded NRECORDS, RECS, or NRECS.
If the option is coded as RECORDS=label, where label is a data |
item label, NM-TRAN understands the data records for the problem |
to start with the first data record of the NM-TRAN data set (at |
the place where the file is positioned before data records are |
read; see the NOREWIND option), and to include as well, those and |
only those subsequent contiguous data records having the same |
value of the data item as does the first record. It counts the |
total number of these data records, minus any comment or dropped |
records, and puts this number in the NONMEM control file. |
In particular, the ID label may be used (or alternatively, the |
option may be coded RECORDS=IR, RECORDS=INDREC, or |
RECORDS=INDIVIDUALRECORD). If a label other than ID is used, the |
$INPUT record must precede the $DATA record. If the data are |
single-subject data, the ID data items used to determine the data |
records for the problem are those labeled ID (not .ID.). |
If there is more than one problem specification with a $DATA |
record that includes an option of the form RECORDS=label, then |
either none of these $DATA records may also include a format |
specification, or all of them must include the same format |
specification. (See records=id). |
LRECL=n2
The number of characters in a logical record. Needed for certain
operating systems (e.g., IBM/CMS).
IGNORE=c1
Specifies that any data record having the character c in column 1
should be ignored, i.e., these records are not included in the
NONMEM data set. This allows comment records to be included in
the NM-TRAN data set. In general, records having the character c
in column 1 will be called "comment records".
Also permitted: IGNORE='c' or IGNORE="c", where c may be any
character except space. IGNORE=# is the default.
IGNORE=@ signifies that any data record having an alphabetic
character or @ as its first non-blank character (not just in
column 1) should be ignored. Alphabetic characters are the
letters A-Z and a-z. This permits a table file having header
lines to be used as an NM-TRAN data set.
IGNORE=(list) |
"List" is a list of one or more data item labels, with logical |
operators and values, of the form "label=value", |
"label.EQ.value", "label.NE.value", "label.GT.value", |
"label.GE.value", "label.LT.value", and "label.LE.value". If the |
logical operator is omitted, the default is "=". With each data |
record, the value of the data item with the given label and the |
value in the list are compared according to the logical operator, |
and if result is "true", the record is ignored, i.e. it is not |
included in the NONMEM data set (see example below). Such records |
are called "dropped records". With "=", ".EQ." and ".NE", the |
value in the data record and the value in the list are compared |
as character strings. Otherwise, they are converted to numeric |
and compared numerically. This comparison is made prior to time |
translation. Hence, the TIME item cannot be compared numerically |
if it contains non-numeric characters such as ":". |
A data item label along with a logical operator and value is |
called a condition. A list may contain several conditions; these |
should be separated by commas, and the list should be enclosed in |
parentheses. Up to 100 different conditions altogether can be |
specified. Multiple IGNORE options with different lists may be |
used. A list may span one or more NM-TRAN records. The use of |
"=" after IGNORE is optional, but parentheses are required with |
this form of IGNORE. Values may be alphabetic or numeric, and |
may optionally be surrounded by single quotes ' or double quotes |
". Quotes are required if a value contains special characters |
such as =. However, a value may not contain spaces or commas. |
No format specification is permitted with this form of IGNORE. |
A data item type may be dropped from the NONMEM data set by means |
of the DROP or SKIP synonym on the $INPUT record, after records |
are dropped due to a condition based on the data item type. |
E.g., |
$INPUT ... GEN=SKIP ... |
$DATA file IGNORE=(GEN='M') |
Records having GEN equal to 'M' will be dropped, and the GEN data |
item type will then be omitted from the NONMEM data set. A |
dropped data item may be any alphanumeric string (without a data |
item delimiter - a blank or a comma). |
If there is more than one condition, then records satisfying at |
least one of these conditions will be dropped. In effect, the |
conditions for dropping a record are connected by the implied |
conjunction ".OR.". E.g. |
IGNORE=(GEN.EQ.1,AGE.GT.60). |
Records having GEN equal to 1 or AGE greater than 60 are dropped. |
All others are accepted. |
ACCEPT=(list) |
The ACCEPT list option is identical to the IGNORE list option, |
except that it specifies conditions for acceptance of records. |
An ACCEPT list cannot be used together with an IGNORE list. E.g. |
ACCEPT=(GEN.EQ.1,AGE.GT.60). |
Records having GEN equal to 1 or AGE greater than 60 are |
accepted. All others are dropped. |
Suppose it is desired that records be dropped that satisfy the |
logical ".AND." of several conditions. This can be implemented |
by using an ACCEPT list with the negations of the conditions. |
For example, suppose that records to be ignored are those having |
GEN=1 .AND. AGE > 60. This may be done as follows: |
ACCEPT=(GEN.NE.1,AGE.LE.60) |
NULL=c2
Specifies that null data items in the NM-TRAN data set are to be
replaced in the NONMEM data set by the character c2. E.g.,
NULL=0 or NULL=..
Null data items consist of a single dot (.) or consecutive com-
mas. c may be any character except space (" ") or semicolon
(";").
Also permitted: NULL='c' or NULL="c", where c may be any charac-
ter.
If this option is omitted, NM-TRAN replaces each null with a
space.
NOWIDE
Requests that NM-TRAN attempt to limit FDATA to 80-character
records. Space between adjacent columns may be suppressed and
multi-line records may be generated. This is the default.
WIDE
Requests that FDATA contain single-line records, and that at
least one space separate columns. (Records in FDATA will never
be wider than 300 characters.) Provides an extra character for
elapsed times, so that they can accommodate the number of hours
in (approximately) 4166 days with a leading space.
NOREWIND|REWIND
With the first problem specification in a control stream, the
file is positioned at its initial point so that the first NM-TRAN
data set in the file is used. The options REWIND and NOREWIND
apply only with a $DATA record in a subsequent problem specifica-
tion, and only when the file named on the record is the same as
that specified for the previous problem. When the file named on
the record is different from that specified for the previous
problem, the file is (re)positioned at its intial point so that
the first NM-TRAN data set in the file is used.
REWIND: Reposition the file at its intial point so that the first
NM-TRAN data set in the file is re-used.
(Whether the file input to NONMEM itself will be repositioned
depends on whether this file is FDATA or is one named in the
$DATA record; see NONMEM Users Guide, Part IV for a complete
explanation.)
NOREWIND: Leave the file at its current position so that the next
NM-TRAN data set in the file is used. The $DATA record with the
previous problem specification must have included the RECORDS
option (or a FINISH record must have terminated the data set used
in the previous problem), so that NM-TRAN did not read to a phy-
sical end-of-file. This is the default.
CHECKOUT
Requests that NONMEM implement the data checkout mode, in which
the PRED routine is not called and predictions, residuals,
weighted residuals and the objective function are not computed.
May also be coded CHECKDATA. No tasks other than $TABLE or $SCAT
can be specified.
NOOPEN
NM-TRAN will not open the named data file. This permits the data
file to be created by one problem and used in a subsequent prob-
lem of the same run. May not be used with options IGNORE, DROP,
or when data items ID, MDV, or EVID must be generated by NM-TRAN.
With NOOPEN, a format specification is required. |
No day-time translation takes place.
LAST20=n3
Override the LAST20 constant in ABLOCK (default: -1).
One or two digit years > LAST20 are assumed to be in the 1900's,
One or two digit years <= LAST20 are assumed to be in the 2000's.
E.g,. suppose LAST20=50. Then two digit years are interpreted as
follows:
00-50 = 2000-2050
51-99 = 1951-1999
TRANSLATE=(list)
"list" describes modifications to be made to the contents of the |
data file. It may contain one of: |
TIME/24, TIME/24.000, TIME/24.00 |
and/or one of |
II/24, II/24.000, II/24.00. |
The options involving TIME (II) can be used to convert the units |
of time (of the steady-state interval) from hours to days. The |
TIME (II) data item is first processed as if the option were not |
present. Then the resulting value is divided by 24. With /24 or |
/24.000, three decimal places are retained in the resulting data |
item. With /24.00, two decimal places are retained in the |
resulting data item. |
Note: The value of TIME is divided by 24, whether or not day-time |
translation occurs (i.e., whether or not relative times are being |
computed by NM-TRAN). Similarly, the value of II is divided by 24 |
whether or not ":" appears in any II data value. |
REFERENCES: Guide III Section V.4, V.5, VII.3.2
REFERENCES: Guide IV Section III.B.5
REFERENCES: Guide V Section 6.4
Go to main index.
Created by nmhelp2html v. 1.0 written by Niclas Jonsson (Modified by AJB 5/2006,11/2007)