A subroutine may be generated from an abbreviated code in an NM-TRAN control stream, as explained in chapter I. Such a routine is called a generated subroutine
or a generated code
Alternatively, a completely-coded FORTRAN subroutine from the NM-TRAN Library may be chosen which will execute in such a way as to have the same effect as the generated code. In this case NM-TRAN must be instructed to generate a table of numbers from the abbreviated code, rather than generate a subroutine, and the Library subroutine will read this table from a file and interpret the numbers in the table so to execute exactly as if a subroutine had been generated. This table is a coded set of instructions to the Library subroutine and its contents are called (generated) Library instructions
The NM-TRAN Library is described in Guide III. Essentially, it consists of one subroutine for each generic type of subroutine for which abbreviated code can be given. When, for example, an abbreviated code for PRED is given, as in the control stream illustrated in chapter I, then the routine PRED can be chosen from the Library to be included in the NONMEM load module. The request to generate Library instructions is given by including the attribute LIBRARY in the $SUBROUTINES record of the control stream; see the section on the $SUBROUTINES record in chapter III. In other words, with this control record:
$SUBROUTINES LIBRARY
Library instructions are generated. When the $SUBROUTINES record does not appear in the control stream, as in the control stream in chapter I, a subroutine is generated. With any given NM-TRAN control stream either Library instructions are generated from all the abbreviated codes, or subroutines are generated, but not both.
When generated subroutines are used, compilation of these subroutines, and linking them with all other routines of the load module, can take place frequently. They can take place whenever any change is made to the control stream, because abbreviated codes are a part of the control stream, and whenever the control stream changes, another generated subroutine is developed. On the other hand, NM-TRAN Library routines can be compiled only once, at the time NM-TRAN is installed, and linking them with all other routines can occur infrequently (for example, only when a new ADVAN subroutine is used from the PREDPP Library). This distinction should be considered when linkage times on one’s system are slow. On the other hand, when special circumstances make it desirable, FORTRAN source code for a generated subroutine can be modified before it is compiled, whereas it is not permitted to modify either the FORTRAN source of a NM-TRAN Library routine or the generated Library instructions.
NM-TRAN takes its input from two files: one file contains the NM-TRAN control stream, and one file contains the NM-TRAN data set. The control stream points to the name of the file containing the data set. For more information about how to run NM-TRAN, see Guide III. NM-TRAN outputs six files with names as shown:
Files 1 and 2 are needed in a NONMEM run and have already been mentioned in chapter I. If NM-TRAN actually modifies the NM-TRAN data set, then the modification, the NONMEM data set, is contained in FDATA. If, though, NM-TRAN does not need to modify the NM-TRAN data set, then the NONMEM data set is simply identified with the NM-TRAN data set and is found in whatever file contains the latter. File 3 contains the FORTRAN-coded subroutines generated from abbreviated codes. At the time NM-TRAN is installed the user chooses whether FORTRAN-coded subroutines supplied by the user are also to be included in File 3. This is the default installation option. All subroutines in File 3 must be compiled and the resulting object modules used in the NONMEM load module. File 4 contains the Library instructions needed by NM-TRAN Library subroutines. If such instructions exist, then File 4 is needed in the NONMEM run; otherwise, File 4 may be ignored. File 5 is also needed in the NONMEM run. The NONMEM file stream is described in Guide I, section B.3. Sometimes a NONMEM run does not need a file stream (see Guide I, section C.3.1). However, whenever NM-TRAN is used before NONMEM, a NONMEM file stream is needed. (This is because with NM-TRAN, the NONMEM data set is never embedded in the NONMEM control stream, and the NONMEM file stream is needed to point to the file containing the NONMEM data set.) File 6 contains a list of all the routines which must be present in a NONMEM load module in order to implement the NONMEM run specified by the NM-TRAN inputs. It may be useful to the user to have this information, but this file is not needed by NONMEM. For more about how this information could be useful, see Guide III.
Examples of Files 1, 2, 3, 5, and 6 are given in Appendix III. These examples result from using the NM-TRAN control stream shown in chapter I along with the NM-TRAN data set shown in Appendix II.
NM-TRAN also outputs a report file containing error messages arising from the program’s efforts to translate the NM-TRAN data set and control stream. When errors are detected, Files 1-6 may be incomplete, and NONMEM should not be run.
A NM-TRAN data set is much like a NONMEM data set. In particular, each data record consists of a sequence of data items, these data items are of the the same types across all data records (unless some data records serve as continuations for others), and the data records are grouped into individual records. An example of a NM-TRAN data set is given in Appendix II, and the first two individual records of this data set are these:
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 . 9.05 6.89 .
1 . 7.03 7.47 .
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 .
This same data set could be used as a NONMEM data set; it conforms to all the requirements of a NONMEM data set. A dot (surrounded by blanks) would be interpreted in a NONMEM run as a data item which is 0. Dots can substitute for 0 data items in order to improve the readability of the data set. Fields of blanks can also be used for the same purpose; see, for example, the NONMEM data set in Appendix III. This is because a FORTRAN format specification for the data set is always supplied in the NONMEM control stream. (Such a format specification can also be supplied in the NM-TRAN control stream, and when it is, fields of blanks can be used in the NM-TRAN data set). However, there are other NM-TRAN data sets which are convenient to use, but cannot be used as NONMEM data sets; NM-TRAN must be used to translate these to NONMEM data sets.
In general, use of NM-TRAN simplifies things for the user. For one thing, it is not required that a FORTRAN format specification be supplied in the NM-TRAN control stream. Without a format specification there really need be no fields of fixed lengths, even though in the example the data items have been lined up (in informal fields of fixed lengths) to improve readability. NM-TRAN understands two data items in a data record to be separated by any number of blanks or by a comma. It recognizes and translates the dot to a field of blanks (or to a field consisting of a specified character preceded by blanks).
Another way to format these data records for NM-TRAN is this:
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,,9.05 6.89
1,,7.03 7.47
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
Notice that two successive commas act as a single dot, and a record may terminate with a data item which is not the last one if the subsequent data items in the record can be represented by dots.
Another way to format these data records for NM-TRAN is this:
1 4.02 9:00 .74 79.6
1 . 9:15 2.84 .
1 . 9:34 6.57 .
1 . 10:07 10.5 .
1 . 11:01 9.66 .
1 . 12:49 8.58 .
1 . 14:06 8.36 .
1 . 18:03 6.89 .
1 . 16:02 7.47 .
1 . 21:07 5.94 .
1 . 33:22 3.28 .
2 4.4 8:00 0. 72.4
2 . 8:16 1.72 .
2 . 8:31 7.91 .
2 . 9:00 8.31 .
2 . 9:55 8.33 .
2 . 11:30 6.85 .
2 . 13:01 6.08 .
2 . 15:02 5.4 .
2 . 17:00 4.55 .
2 . 20:00 3.01 .
2 . 32:18 .90 .
Here the third data item of each record, which is a value of time in hours, has been expressed as a clock time, rather than as a relative time. NM-TRAN can accept clock time; NONMEM (and PREDPP) cannot. NM-TRAN translates a clock time to a relative time. Information in the NM-TRAN control stream indicates that translation of this type should be performed; see section III.B.2. When this is done, all times in the NM-TRAN data set are assumed to be clock times. A clock time is either of form hr:min, as in the example, or hr.fr, where fr is a decimal fraction of the hour to two digits, using a military clock in both cases. E.g. 2:45PM can be expressed either as 14:45 or 14.75.
Yet another way to format these data records for NM-TRAN is this:
1 4.02 10/1 9:00 .74 79.6
1 . 10/1 9:15 2.84 .
1 . 10/1 9:34 6.57 .
1 . 10/1 10:07 10.5 .
1 . 10/1 11:01 9.66 .
1 . 10/1 12:49 8.58 .
1 . 10/1 14:06 8.36 .
1 . 10/1 18:03 6.89 .
1 . 10/1 16:02 7.47 .
1 . 10/1 21:07 5.94 .
1 . 10/2 9:22 3.28 .
2 4.4 10/1 8:00 0. 72.4
2 . 10/1 8:16 1.72 .
2 . 10/1 8:31 7.91 .
2 . 10/1 9:00 8.31 .
2 . 10/1 9:55 8.33 .
2 . 10/1 11:30 6.85 .
2 . 10/1 13:01 6.08 .
2 . 10/1 15:02 5.4 .
2 . 10/1 17:00 4.55 .
2 . 10/1 20:00 3.01 .
2 . 10/2 08:18 .90 .
Here calendar dates have been included, and clock time has been treated modulo 24 hours. These dates are called date data items
Information in the NM-TRAN control stream indicates that translation with this type of data should be performed; see section III.B.2. Information in the NM-TRAN control stream also indicates that the date data items should not appear in the NONMEM data set; only the relative time data items should appear where clock time data items appear. More generally, instead of month followed by day in date data items, day can follow month, and year can also be included at either the beginning or end of the data items. Or, only day need be given. Again, the choice of format in this regard is specified in the control stream. Regardless of format, with any date data item any non-numeric character, except comma or blank, can separate the date fields. Here are some examples of possibilities: 10/1, 10-1, 10-1-1986, 10-1-86, 86-10-1. Two digit years are assumed to be in the 1900’s. Leap years are recognized; they are years 4, 8, 12, etc. If year is omitted from the format, the year is assumed to be year 0, which is not a leap year. When the date data items only give days (months and years are missing), then these data items can be any positive or negative integers, and for the purpose of computing relative times, they are ordered in the same way as are the integers.
NM-TRAN makes a distinction between population data and single-subject data; see section C.4. If the data are population data, then the clock time in the first data record of an individual record is translated to relative time 0. If the data are single-subject data, then the clock time in the first data record of the data set is translated to relative time 0. If PREDPP is used, then a time on a reset or reset-dose event record is translated to relative time 0, whether the data type is population or single-subject.
Comments can be included in NM-TRAN data sets. E.g.
1 . 12.12 5.94 .
1 . 24.37 3.28 .
C This next individual may be an outlier
2 4.4 0. 0. 72.4
2 . .27 1.72 .
If requested, any (FORTRAN) record with a designated character in position 1 is ignored, i.e. it does not appear in the NONMEM data set. The character used in position 1 must be the same for all comment records; it is specified in the $DATA record (see section III.B.5).
NONMEM data records are grouped into contiguous sets of records called individual records
With population data, where there are multiple observations from multiple subjects, an individual record contains the data records associated with a given subject. Each data record of the individual record has the same ID data item. NONMEM can also be used to analyze data from a single subject. With such data, and when each observation consists of a single number, an individual record is simply any group of contiguous data records including only one observation record and having the same ID data item if the number of data records in the group is two or more. When a multivariate observation is present, the individual record containing it includes several observation records, each containing one element of the observation.
The inclusion of ID data items in a data set with single-subject data is a little unnatural, and it is not commonly required by computer programs that are meant to be used only with single-subject data, With single-subject data, NM-TRAN automatically generates the ID data items required in a NONMEM data set. Such ID data items are called generated ID data items Usually, this is advantageous. There are situations, though, where the generated ID data items are not appropriate, and then generated ID data items should be disallowed; see below. Most notably, such a situation occurs when multivariate observations are included in the data set. The mechanism for disallowing generated ID data items is given in sections C.4.2 and III.B.2.
NM-TRAN "recognizes" the difference between population data and single-subject data † (NONMEM itself does not make such a distinction.) A data set consisting of population data is called a population data set
A data set consisting of single-subject data is called a
single-subject data set †
----------
The only consequence of NM-TRAN’s ability to recognize this difference between data types is to allow ID data items to be auotomatically generated with single-subject data. NM-TRAN infers from information in the control stream whether the data are of one type or the other. The way this is done is outlined next. For details, see section C.4.2.
Both NONMEM and NM-TRAN explicitly recognize two types of random variables, @eta@-variables and @epsilon@-variables. These two types are nested, i.e. for any set of fixed values for the @eta@-variables, the @epsilon@-variables can assume different values, but not conversely. The @epsilon@ variables can only occur along with @eta@ variables, and then they represent random intraindividual effects, while the @eta@ variables represent random interindividual effects. If control stream information indicates that @epsilon@ variables occur in the statistical model, then population data are inferred. To infer population data when the @epsilon@ variables occur is consistent with the fact that with population data there are both random intersubject and random intrasubject effects in the statistical model; then the interindividual (intraindividual) effects are identified with the intersubject (intrasubject) effects. (However, for noncontinuous population data see the discussion below.)
If population data are not inferred, then only @eta@ variables occur in the model. These variables, occuring by themselves, are nonnested variables. They can represent either intersubject effects or intrasubject effects. (The terms ’intrasubject’ and ’intraindividual’ are used interchangeably, but the term ’interindividual’ is reserved; see below.) With single-subject data there is no subject-to-subject variability, and the @eta@ variables represent intrasubject effects. When each observation comes from a different subject, either the data are regarded as population data and @epsilon@ variables are used, or more usually, intrasubject variability is not distinguishable from intersubject variability, and @eta@ variables only are used to represent the one type of random effect. As long as only @eta@ variables occur in the statistical model and the observations are taken to be statistically independent, it really makes no difference whether the @eta@ variables are regarded as representing intersubject or intrasubject random effects. Statistically, the observations being modeled can be regarded as arising from a single subject, or each observation can be regarded as coming from a different subject. The NONMEM convention is to take a "middle position". The term individual is used to mean an individual observation in the population of observations. Thus no matter how the data actually arise, the @eta@ variables can be regarded as representing interindividual effects. Moreover, in deference to the often-occuring pharmacokinetic study where data arise from a single-subject, when the data are not recognized as population data, they are called single-subject data, even when different observations actually arise from different subjects. This convention conforms with a convention of PREDPP, whereby when only nonnested random variables occur, the data are regarded as single-subject data (Guide VI, section IV.A).
With single-subject data, each observation must be in a different individual record (this requirement is a consequence of the fact that the @eta@ variables represent interindividual effects). Accordingly, if one wants to extract an individual record from a population data set and use this record as a single-subject data set (a new NM-TRAN data set), the ID data items in this record must be changed since they are all equal. In this case one might allow NM-TRAN to generate new ID data items for the single-subject data set. At the same time one might (but one need not) instruct NM-TRAN to exclude the old ID data items from the NONMEM data set (see discussion of the DROP attribute in section III.B.2). Whether or not one does the latter, NONMEM will be properly instructed to use only the new ID data items.
There are single-subject data sets where generated ID data items should be disallowed. One example is where there are multivariate observations. Each element of the multivariate observation must be placed on a different data record, but each of these records must be included in the same individual record. Were generated ID data items allowed, a multivariate observation would span more than one individual record. In this example, the user must include appropriate ID data items in the NM-TRAN data set.
Another example is where the data are population data in the sense that multiple observations are obtained from multiple subjects, but because @epsilon@ variables are not used in the statistical model, NM-TRAN infers that the data are single-subject. This situation arises when, for example, the data are categorical, rather than continuous. Then @eta@ variables still represent random interindividual effects, and random intraindividual variablity exists, but it is expressed without the use of @epsilon@ variables. Were generated ID data items allowed, observations from a given subject would not be properly identified with that subject.
NM-TRAN infers that the data are population data when at least one of the following is true of the control stream:
|
1. |
An abbreviated code is present which uses EPS’s. |
|
See section IV.A |
|
2. |
An abbreviated code is present which uses ETA’s, and an abbreviated code is present (perhaps the same one) which uses ERR’s. |
|
See section IV.A |
|
3. |
A $SIGMA record is used. |
|
See section III.B.11. |
|
4. |
A $MSFI record is used with the option NPOPETAS=n, where n is positive. |
|
See section III.B.12. |
|
5. |
With PREDPP: no $PK record is used, and a $OMEGA record precedes a $ERROR record. |
|
See section V.C.6 |
When none of the above is true, the data are inferred to be single-subject data. In this case NM-TRAN generates ID data items unless this is disallowed by the presence of the reserved label L1 on the $INPUT record (see section III.B.2). Generated ID data items have values 1 and 2.
When each data record includes an actual observation, then the generated ID data items alternate between 1 and 2 with every data record. More precisely, when MDV (missing dependent variable) data items do not appear in the NM-TRAN data set, or when NM-TRAN does not automatically include them in the NONMEM data set (see section V.B), then the generated ID data items alternate between 1 and 2 with every data record. Suppose, though, that either MDV data items appear in the NM-TRAN data set, or are automatically included by NM-TRAN in the NONMEM data set. Then the generated ID data items alternate between 1 and 2, remaining constant over a group of contiguous data records with MDV=1.
For an example, see Appendix IV.
TOP
TABLE OF CONTENTS
NEXT CHAPTER ...