89  Prior and Initialization Records

1 $ETAS and $PHIS Record For Inputting Specific Eta or Phi values (NM73)

Sometimes it is desired to bring in specific eta or phi values and using them as initial values, just as is done for THETAs using the $THETA record. The simplest syntax is to enter a single set of etas:

$ETAS 0.4 3.0 3.0 5.0

from the control stream file. All of the subjects in the data set will be given these set of initial values of etas. Alternatively, enter them as phi values, convenient for EM methods:

$PHIS 0.4 3.0 3.0 5.0

The eta values will then be evaluated as eta(i)=phi(i)-mu(i) for each eta, where mu(i)=mu_i is evaluated according to their definitions in the $PK section.

Alternatively, enter initial etas and/or phis for an entire set of subjects from a .phi or .phm (in the case of mixture problems) of a previous analysis:

$ETAS FILE=myprevious.phi FORMAT=s1pE15.8 TBLN=3

Where FORMAT should at least have the delimiter appropriate to read the file, and TBLN is the table number in the file. If TBLN is not specified, then the first set of etas/phis are brought in. In matching the etas/phis to the data set given in $DATA of the control stream file, the attempt will be to match ID numbers rather than subject numbers, if an ID column in the file exists, which it will, if you are using a .phi or .phm file generated from a previous nonmem analysis. The phc/etc variances will also be brought in. Make sure that subject numbers and/or ID numbers match up uniquely and unambiguously to the subjects of the data set given in $DATA, so there is no possibility of confusion (which is not an issue if the .phi file produced by the control stream used the same data structure as the present control stream). As of nm760, contents from a .iph file can be brought in. As a .iph file has both ETA() and PHI() items, ETA()’s will be selected for a $ETAS record, and PHI() will be selected for a $PHIS record. The first ITERATION>0 is selected, unless a particular iteration is specified, for example:

$ETAS FILE=myprevious.iph TBLN=3 ITERATION=123

The etas inputted by $ETAS/$PHIS can be used in several ways. In BAYES, SAEM, and IMP MAPITER=0 they are used as the starting etas (in the first iteration). In MAP estimation matters, such as METHOD=1, or ITS, or IMP MAPITER>0, or IMPMAP, and if MCETA>0, then these etas are one of the initial eta vector positions tested (during the first iteration), and the one giving the lowest OBJ is then selected. In cases where FNLETA=2, the estimation step is skipped, and etas inputted from $ETAS are passed directly to the Final processing steps. That is, these etas are treated as if they were the final result of an estimation. The final processing steps use routines such as FNLETA, FNLMOD, PRRES, NP4F, that contribute to generating $TABLE, $SCATTER outputs, including the various WRES diagnostics, where applicable. When METHOD=0, these initial etas are not used, as this method does not require initial etas.

One purpose to bringing initial eta/phi and etc/phc values is you can readily resume an analysis, if an MSF file was not set up in the previous analysis (the MSF file system is still the most complete information transfer for resuming an analysis):

$PROB RUN# example3 (from ad1tr1m2s)
$INPUT C SET ID JID TIME CONC=DV DOSE=AMT RATE EVID MDV CMT VC1 K101 VC2 K102 SIGZ PROB
$DATA example3.csv IGNORE=C
$SUBROUTINES ADVAN1 TRANS1
$MIX
P(1)=THETA(5)
P(2)=1.0-THETA(5)
NSPOP=2
$PK
MU_1=THETA(1)
MU_2=THETA(2)
MU_3=THETA(3)
MU_4=THETA(4)
VCM=DEXP(MU_1+ETA(1))
K10M=DEXP(MU_2+ETA(2))
VCF=DEXP(MU_3+ETA(3))
K10F=DEXP(MU_4+ETA(4))
Q=1
IF(MIXNUM.EQ.2) Q=0
V=Q*VCM+(1.0-Q)*VCF
K=Q*K10M+(1.0-Q)*K10F
S1=V
$ERROR
Y = F + F*EPS(1)
$THETA 4.3 -2.9 4.3 -0.67 0.7
$OMEGA BLOCK(2)
 .04
 .01 .027
$OMEGA BLOCK(2)
 .05
 .01 .06
$SIGMA
0.01
$PHIS FILE=etafile3_phi.phm FORMAT=S1PE15.7 TBLN=3
$EST METHOD=CHAIN FILE=etafile3.chn ISAMPLE=5 NSAMPLE=0
$EST METHOD=IMP MAPITER=0 CTYPE=3 INTERACTION NSIG=3 PRINT=1 NITER=3

Or, use FNLETA=2 to use the etas that were brought in to evaluate predicted values, without performing a new population estimation:

$PROB RUN# Example 1 (from samp5l)
$INPUT C SET ID JID TIME DV=CONC AMT=DOSE RATE EVID MDV CMT CLX V1X QX V2X SDIX SDSX
$DATA etafile.csv IGNORE=C
$SUBROUTINES ADVAN3 TRANS4
$PK
MU_1=THETA(1)
MU_2=THETA(2)
MU_3=THETA(3)
MU_4=THETA(4)
LCL=MU_1+ETA(1)
CL=DEXP(LCL)
LV1=MU_2+ETA(2)
V1=DEXP(LV1)
LQ=MU_3+ETA(3)
Q=DEXP(LQ)
LV2=MU_4+ETA(4)
V2=DEXP(LV2)
S1=V1
$ERROR
IPRED=F
Y = F + F*EPS(1)

; Initial values of THETA
$THETA 1.68693E+00 1.61129E+00 8.19604E-01 2.39161E+00

;INITIAL values of OMEGA               1.24115E-02  1.59565E-02  1.87547E-01 -1.27356E-02
$OMEGA BLOCK(4)

 1.65062E-01 -7.41489E-04 1.31429E-01
1.39056E-02 3.32699E-02 1.49906E-01
;Initial value of SIGMA
$SIGMA
5.71632E-02 ;[P]

$ETAS FILE=etafile_phi.phi FORMAT=S1PE15.7 TBLN=6

$EST METHOD=1 INTERACTION NSIG=3 PRINT=1 FNLETA=2
$TABLE ID CL V1 Q V2 FIRSTONLY NOAPPEND NOPRINT FILE=etafile.par FORMAT=,1PE13.6
$TABLE ID ETA1 ETA2 ETA3 ETA4 LCL LV1 LQ LV2 FIRSTONLY NOAPPEND NOPRINT FILE=etafile.eta
$TABLE ID TIME IPRED DV CPRED CWRES NOAPPEND ONEHEADER FILE=etafile.tab NOPRINT

2 Improved Flexibility for using PRIOR information in TNPRI Problems (nm75)

A typical setup for using prior information from a first run (control stream), and using $PRIOR TNPRI for a second run, is to specify the MSFO file in the first run (call it pre_tnpri). In the second run, the MSF file is picked up with an MSFI record, and the first $PROB imports the prior information:

while the second $PROB evaluates the problem with a TNPRI prior:

$PROB Read in MSFI file.
$INPUT C SET ID JID TIME DV=CONC AMT=DOSE RATE EVID MDV CMT
$DATA example1b.csv IGNORE=C
$MSFI pre_tnpri.msf ONLYREAD
$SUBROUTINES ADVAN=3 TRANS4
$PK
MU_1=THETA(1)
MU_2=THETA(2)
MU_3=THETA(3)
MU_4=THETA(4)
CL=DEXP(MU_1+ETA(1))
V1=DEXP(MU_2+ETA(2))
Q=DEXP(MU_3+ETA(3))
V2=DEXP(MU_4+ETA(4))
S1=V1
$ERROR
Y = F + F*EPS(1)

$PRIOR TNPRI (PROBLEM 2) IFND=0 MODE=0 PLEV=0 IVAR=0
$EST OMIT

Then, the information is used in the next $PROB (problem 2 in the same control stream) to be used as prior information:

$PROB Evaluation
$INPUT C SET ID JID TIME DV=CONC AMT=DOSE RATE EVID MDV CMT
$DATA example1b.csv IGNORE=C REWIND
$THETA (0.001, 2.0)x4
$OMEGA BLOCK(4) VALUES(0.15,0.01)
$SIGMA
(0.6 ) ;[P]

$EST METHOD=1 INTERACTION NSIG=3 PRINT=10 NOABORT MAXEVAL=9999
         FORMAT=S1PE23.15

$COV MATRIX=R PRINT=E UNCONDITIONAL

Keep in mind that the MSF file will contain the last covariance analysis performed in pre_tnpri. This includes covariance analysis for IMP, SAEM, BAYES, or SIR.

IVAR=0: Uses Rinv variance-covariance of a former problem (as of NMVI), if former problem used METHOD=1. If former problem used EM, BAYES, or SIR method, will retrieve the variance-covariance matrix that was specified with $COV MATRIX in the former problem.

IVAR=1: Uses Rinv*S*Rinv of a former problem (as of NMVI)

IVAR=2: Uses S of a former problem (as of nm75)

As of nm75, to use S-matrix assessed variance-covariance in a TNPRI problem, set IVAR=2:

$PRIOR TNPRI (PROBLEM 2) IFND=0 MODE=0 PLEV=0 IVAR=2

Make sure that when requesting the appropriate variance type, this was computed for the previous problem. For example, if METHOD=1, and $COV MATRIX=R was set for the previous problem, then S matrix is not available for the present problem and IVAR=2 should not be used. For IMP, SAEM, BAYES, or SIR evaluated covariances from the previous problem, use IVAR=0 for the present problem, regardless of whether $COV MATRIX=R, S, or RSR (no MATRIX specification) was used.

To have more flexibilty in inputting desired prior information from text files, see the section below on $RCOV.

3 $RCOV and $RCOVI Record For Inputting Variance-Covariance information from another problem (NM75)

The $RCOV record can be used to bring in variance-covariance matrix of estimates results from a previous problem, and use it for subsequent use in assessing total standard errors of table items without having to re-calculate the variance with a $COV step. Consider the control stream snippet below that brings in the covariance-variance of estimates from a previous control stream, located in rcov.cov, to be used in

$EST METHOD=1 FNLETA=2 FORMAT=,1PE23.15
$RCOV FILE=rcov.cov TBLN=1 DELIM=,
$TABLE ID TIME IPRED CL V1 Q V2 LTVCL VARCALC=3 FILE=rcov3.tab NOPRINT NOAPPEND

Or, the record $RCOVI may be used to bring in the variance-covariance information from the inverse-covariance file:

$RCOVI FILE=rcov.coi TBLN=1 DELIM=,

So, $RCOV reading in variance-covariance from rcov.cov of a previous run can be used in place of executing the $COV step, and then used in evaluating the total standard error for table items (VARCALC=3). Thus, you may bring in a variance-covariance evaluated by any possible method (IMP, SAEM, BAYES, SIR) from the previous run, and use it for evaluating total standard errors of table items.

As another example, final parameter results using the $CHAIN record, and final empirical Bayes estimates of etas (and their covariances) using the $ETAS record, may also be read in from the previous run:

$CHAIN FILE=rcov.ext NSAMPLE=0 ISAMPLE=-1000000000 FORMAT=,1PE23.15
$ETAS FILE=rcov.phi TBLN=1 DELIM=,
$RCOV FILE=rcov.cov TBLN=1 DELIM=,

The final THETAs, SIGMAs, OMEGAs, etas, covariances of etas, and covariances of THETAs, OMEGAs and SIGMAs from the previous run can then be used without any re-estimation by setting FNLETA=2, and without any re-evaluation of the $COV step.

$EST METHOD=1 FNLETA=2 FORMAT=,1PE23.15
$TABLE ID TIME IPRED CL V1 Q V2 LTVCL VARCALC=3 FILE=rcov3.tab NOPRINT
            NOAPPEND

$RCOV can also be used to import a prior in a $PRIOR TNPRI problem, replacing the variance-covariance that was last written to an MSF file with alternative values. This may have value if you wish to use variance-covariance estimated by an alternative method in a previous run, (IMP, SAEM, BAYES, SIR), and use it as the prior in a TNPRI problem. A proper MSFI file was generated from a previous run (call it pre_tnpri), and it is desired to input variance-covariance from another source, perhaps yet another previous run (call it sirsampling, because the SIR assessed covariance will be used), so that the contents of the MSFI file, along with the $RCOV record, are read in on the first problem:

$PROB Read in MSFI file.
$INPUT C SET ID JID TIME DV=CONC AMT=DOSE RATE EVID MDV CMT
$DATA example1b.csv IGNORE=C
;Comment out ONLYREAD in next line if msf file does not contain covariance
;step. If covariance step failed, it should still be okay to use ONLYREAD
$MSFI pre_tnpri.msf ONLYREAD
$SUBROUTINES ADVAN=3 TRANS4
$PK
MU_1=THETA(1)
MU_2=THETA(2)
MU_3=THETA(3)
MU_4=THETA(4)
CL=DEXP(MU_1+ETA(1))
V1=DEXP(MU_2+ETA(2))
Q=DEXP(MU_3+ETA(3))
V2=DEXP(MU_4+ETA(4))
S1=V1
$ERROR
Y = F + F*EPS(1)

; Bring in prior means
$CHAIN FILE=sirsampling.ext ISAMPLE=-1000000000 NSAMPLE=0
; Bring in prior variance
$RCOV FILE=sirsampling.cov TBLN=3 DELIM=S
$PRIOR TNPRI (PROBLEM 2) IFND=0 MODE=0 PLEV=0 IVAR=0
$EST OMIT

Then, the information is used in the next $PROB (same control stream) to be used as prior information:

$PROB Evaluation
$INPUT C SET ID JID TIME DV=CONC AMT=DOSE RATE EVID MDV CMT
$DATA example1b.csv IGNORE=C REWIND
$THETA (0.001, 2.0)x4
$OMEGA BLOCK(4) VALUES(0.15,0.01)
$SIGMA
(0.6 ) ;[P]

; Optionally retrieve initial THETAs, OMEGAs, SIGMAs from a $CHAIN record
$CHAIN FILE=sirsampling.ext ISAMPLE=37 NSAMPLE=0
$EST METHOD=1 INTERACTION NSIG=3 PRINT=10 NOABORT MAXEVAL=9999
         FORMAT=S1PE23.15
$COV MATRIX=R PRINT=E UNCONDITIONAL

Final parameter estimates from a previous run may also be entered in using the $CHAIN record, as shown above, to serve as the centrality parameters of the prior.

The lower and upper bound settings in the $THETA record on the second problem normally must match those of the problem that generated the prior. To get around this, you can set the NOMSFTEST option on the $MSFI record in the first problem. You will still get warnings if the bounds do not match.

Alternatively, you can omit an MSFI input altogether as follows:

$PROB Read in MSFI file.
$INPUT C SET ID JID TIME DV=CONC AMT=DOSE RATE EVID MDV CMT
$DATA example1b.csv IGNORE=C
;$MSFI pre_tnpri.msf ONLYREAD
$SUBROUTINES ADVAN=3 TRANS4
$PK
MU_1=THETA(1)
MU_2=THETA(2)
MU_3=THETA(3)
MU_4=THETA(4)
CL=DEXP(MU_1+ETA(1))
V1=DEXP(MU_2+ETA(2))
Q=DEXP(MU_3+ETA(3))
V2=DEXP(MU_4+ETA(4))
S1=V1
$ERROR
Y = F + F*EPS(1)

; If no MSFI file, then enter $THETA, $OMEGA, $SIGMA records with some
; type of reasonable starting values. Only boundary values will be used,
; however, for internal parameterization.
$THETA (0.001, 2.0)x4
$OMEGA BLOCK(4) VALUES(0.15,0.01)
$SIGMA
(0.6 ) ;[P]

; Bring in prior means
$CHAIN FILE=sirsampling.ext ISAMPLE=-1000000000 NSAMPLE=0
; Bring in prior variance
$RCOV FILE=sirsampling.cov TBLN=3 DELIM=S
$PRIOR TNPRI (PROBLEM 2) IFND=0 MODE=0 PLEV=0 IVAR=0
$EST OMIT

Then, the information is used in the next $PROB (same control stream) to be used as prior information:

$PROB Evaluation
$INPUT C SET ID JID TIME DV=CONC AMT=DOSE RATE EVID MDV CMT
$DATA example1b.csv IGNORE=C REWIND
$THETA (0.001, 2.0)x4
$OMEGA BLOCK(4) VALUES(0.15,0.01)
$SIGMA
(0.6 ) ;[P]

; Optionally retrieve initial THETAs, OMEGAs, SIGMAs from a $CHAIN record
$CHAIN FILE=sirsampling.ext ISAMPLE=37 NSAMPLE=0
$EST METHOD=1 INTERACTION NSIG=3 PRINT=10 NOABORT MAXEVAL=9999
         FORMAT=S1PE23.15
$COV MATRIX=R PRINT=E UNCONDITIONAL

Final parameter estimates from a previous run may also be entered in using the $CHAIN record, as shown above, to serve as the centrality parameters of the prior.