+--------------------------------------------------------------------+
| |
| FINEDATA |
| |
+--------------------------------------------------------------------+
MEANING: FINEDATA program
CONTEXT: NONMEM run
USAGE:
..\util\finedata fineplot.ftl
..\util\finedata < fineplot.ftl
DISCUSSION:
The utility program finedata augments an NM-TRAN data file to incorpo-
rate additional, non-observation, time values spaced at regular incre-
ments so that when a table is generated, NONMEM can fill these records
with predicted values, from which smooth prediction curves may be
plotted. If data items DV, EVID and/or MDV are listed in $INPUT and
are present in the input data records, inserted records will be given
the following values by default
DV=.
EVID=0
MDV=1
This may be over-ridden by a data item specification, such as $FINE-
DATA EVID=2. See also the EXAMPLE below.
Alternately, finedata can be used to fill in missing covariate values,
but not to add any additional records.
fineplot.ctl is the name of a control stream file containing special
commands for the finedata program.
The only records that finedata pays attention to is $INPUT, from which
it obtains the column names, $DATA, from which it obtains the input
data file, $FINEDATA, which contains instructions, and $PROB by which
problems are separated.
With NONMEM 7.4, the $EXTRADOSE record may be used to add additional |
non-observation dose records to those already existing, but it allows |
items such as compartment number, or EVID, etc., to vary. The EXTRA- |
DOSE has particular value when adding time-delay compartments to a |
model, to deal with time-delay problems. For details: |
See INTRODUCTION TO NONMEM 7, finedata Utility Program
All other control stream records are ignored. All options of $DATA
are ignored, including RECORD and IGNORE options. (Input records
whose first non-blank character is alphabetic are copied to the out-
put file but not used otherwise.) Thus, a way to create a control
stream is to copy the first records describing the data layout from an
existing NONMEM control stream file, and then adding the $FINEDATA
record.
Multiple data sets may be processed by one finedata control stream
file, by using $PROB records to separate the problems.
The options to $FINEDATA are as follows:
$FINEDATA
FILE= filename
AXIS= label[(LIN) | (LOG)]
NEVAL= [n | label ] | [TDELTA= [x | label ]
[TSTART= [x | label | FIRST ]]
[TSTOP= [x | label | LAST ]]
[OCC= label ]
[item= list] ...
[item= [PREV | NEXT] [LIN | LINLIN | LOG | LOGLIN ]] ...
[DELIM=s | DELIM=t | DELIM=, ]
[MISSING=list ]
$EXTRADOSE ... |
SAMPLE:
$FINEDATA TSTART=0 TSTOP=50 NEVAL=100 AXIS=TIME(LIN) CMT=1,3
FILE=example6b.csv
OPTIONS:
FILE=filename
Required. The name of the output file.
AXIS= label[(LIN) | (LOG)]
Required. Name of column containing times, usually TIME.
Optionally, designate (LIN) or (LOG) in parenthesis, to indicate
linear or geometric time incrementing when new records are incor-
porated.
If LIN: additive time increment=(tstop-tstart)/(neval+1)
If LOG: multiplicative time incre-
ment=(tstop/tstart)**(1/(neval+1))
Times may be entered as numerical values, or in hh:mm:ss format.
Data sets with DATE/TIME records may also be processed (but then
TSTART and TSTOP must be in numerical hours or hh:mm:ss format).
NEVAL= [ n | label ]
The number of additional incremental time records to be created
per subject. Either an integer value n, or the label of a data
item in the original data set containing the NEVAL value. When
NEVAL=-1, then missing values will be filled in for specified
items, but no additional records will be created. If NEVAL/=-1,
only the inserted records will have filled in interpolated val-
ues, and the original records will remain untouched.
Optional. One of NEVAL or TDELTA is required.
TDELTA= [x | label ]
The increment in time. Either a number, or the label of a data
item in the original data set containing the TDELTA value.
Optional. One of NEVAL or TDELTA is required.
TSTART= [ x | label | FIRST ]
Optional. Default: FIRST
The start time for creating incremental time records. Either a
real or integer numeric value x, or the label of a data item in
the original data set containing the start time. If TSTART is
not a number and is not FIRST, then it is interpreted as the
label of a data item in the original data set containing the
start time. If omitted or coded as FIRST, then the time of the
first record of the subject. When TSTART is given by a data
item, it can differ according to occasion. The same holds true
for TSTOP and NEVAL (see below) if they are obtained from the
data file.
TSTOP= [ x | label | LAST ]
Optional. Default: LAST
The stop time for creating incremental time records. Either a
numeric value real or integer x, or the label of a data item in
the original data set containing the stop time, or LAST, in which
case the last record of the subject or occasion or time section
is used.
Finedata stops inserting records when occasion changes (if OCC=
was given), or if EVID=3 or 4, or after a re-initialization of
time (indicated by the time in the data record being less than
that of the previous record). TSTART will be the next TIME
value.
OCC= label
Optional. Restart the time incrementing when the occasion
changes, in addition to the other conditions listed above.
item= list
List of values for data item ITEM for which there is to be a
record at each time increment. May be a list of values such as
1,3 etc. This can be done for a series of data items. For exam-
ple, if you enter $FINEDATA CMT=1,3 EVID=2,2 then two records per
time point are inserted, one with CMT=1, EVID=2, and the other
with CMT=3, EVID=2.
item= [LAST | NEXT] [LIN | LINLIN | LOG | LOGLIN ] ...
A scheme to determine how to supply values to various data items
for these inserted records may also be given. The following may
be interspersed with numeric values.
NEXT: When inserting records between two consecutive original
records of time t1 (PREV) and t2 (NEXT), the PREDPP's default of
using the covariate value of the t2 (NEXT) record is used for the
inserted records. NEXT is the default.
PREV: When inserting records between two consecutive original
records of time t1 (PREV) and t2 (NEXT), the covariate value of
the t1 (PREV) record is used for the inserted records. (LAST may
be coded instead of PREV, to be consistent with the options of
the $BIND record. Note that the $BIND record is not used by
finedata.)
LIN, or LINLIN: A covariate-linear, time-linear interpolation is
used for the covariate value for the inserted records. LINT or
LINLINT (T for truncate) produces truncated integer values, LINR
or LINLINR (R for round) produces values rounded to the nearest
integer.
LOG, or LOGLIN: A covariate-logarithmic, time-linear interpola-
tion is used for the covariate value for the inserted records. A
T or R suffix results in truncated or rounded integer values,
respectively.
LINLOG: A covariate-linear, time-logarithmic interpolation is
used for the covariate value for the inserted records. A T or R
suffix results in truncated or rounded integer values, respec-
tively.
LOGLOG: A covariate-logarithmic, time-logarithmic interpolation
is used for the covariate value for the inserted records. A T or
R suffix results in truncated or rounded integer values, respec-
tively.
DELIM=x
Optional. DELIM=delimiter of output data file, if it is to be
different from the input data file. DELIM=S is space, DELIM=t is
tab, DELIM=, is comma.
MISSING=list
Optional. List is a comma delimted list of symbols that denote
missing values. By default, a period (.) and space (s) are con-
sidered missing values. Values such as 0 or -99 may be present
in the data as symbols for missing values. They may be described
with MISSING=0 or MISSING=-99. During interpolation, missing
values will be skipped, and only records with non-missing values
will be used for interpolation.
EXAMPLE:
With NONMEM 7.3 and higher, if an MDV is set to a value greater than
or equal to 100, it is converted to that value minus 100 upon input,
but will also not be used at all during estimation, only for table
outputting. This option allows you to use the same enhanced data file
for estimation and Table outputs, without significantly slowing down
the estimation. So, the finedata control stream file might include
$FINEDATA TSTART=0 TSTOP=50 NEVAL=100 AXIS=TIME(LIN)
CMT=1,3 MDV=101,101 FILE=example6b.csv
See Guide Introduction_7 for details and examples.
REFERENCES: Guide Introduction_7
Go to main index.
Created by nmhelp2html v. 1.0 written by Niclas Jonsson (Modified by AJB 5/2006,11/2007,10/2012)