$THETAI, $THETAR

Gives Instructions for transforming initial ($THETAI) and final ($THETAR) THETAs (or $THETAP when $THETAI is used). Can also be encoded as $THI and $THR, respectively.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17


   $THETAI  Fortran statements
   $THETAR  Fortran statements

  ;# EXAMPLE ($THETAI)
   $THI
   THETA(1:NTHETA)=LOG(THETAI(1:NTHETA))
   THETAP(1:NTHP)=LOG(THETAPI(1:NTHP))

   THETA=LOG(THETA)

  ;# EXAMPLE ($THETAR)
   $THETAR
   THETAR=EXP(THETA)
  ;# or
   $THETAR
   THETAR(1:NTHETA)=EXP(THETA(1:NTHETA))
   THETAPR(1:NTHP)=EXP(THETAP(1:NTHP))

Initial THETAs in the $THETA record may be functionally transformed with the $THETAI record, and final THETAs may then be reverse transformed for report purposes using $THETAR. This has particular value when it is desired that the THETAs by estimated within NONMEM in the log domain, but you want the convenience of inputting and outputting them in the natural domain, such as when performing linear MU referencing. In the above sample code, THETAs are estimated in the log domain but input and output are in the natural domain, as it is particularly convenient when performing linear MU referencing.

The following snippet from "example/thetair" shows how the transformations are used for a multiplicative ETA model.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19


;#...
$SUBROUTINES ADVAN3 TRANS4

$THETAI
THETA=DLOG(THETAI)

$THETAR
THETAR=DEXP(THETA)

$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))
;#...

Note the use of informative names for the prior information. See Introduction to NONMEM 7 I.44 "A Note on Setting up Prior Information".

$THETAI

The $THETAI record will convert any initial THETAs in a $THETA record, or THETAs obtained from a chain file, but will not convert THETAs from an MSF file. The variance to the theta priors will be appropriately converted when using $PRIOR NWPRI.

The assignment statements may be any Fortran 95 statements. They are copied unchanged to subroutine SUBROUTINE THETAISUB in FSUBS (also found in thetair.f90).

They may include array assigment statements specifying the whole arrays or sections of arrays.

When using $THETAI, be aware that the any bounds described in the $THETA record are also submitted to the $THETAI transformations. Therefore, bounds that are likely to cause a domain error in the transformation process should not be included. For example, When Theta is log transformed, the lower bound of 0 and its proximity should not be included. The transformation itself will prevent reported THETAs from being less than 0.

1
2
3
4
5
6
7


  $THI
  THETA(1)=LOG(THETAI(1))
  ;#...
  $THETA
  (0,5.0) ;# wrong
  $THETA
  (0.1,5.0) ;# OK.

Arguments of the subroutine are as follows.

THETAI Values of THETA specified on $THETA records. Input.
THETAPI Values of THETA specified on $THETAP records (or, if the informative names are not used, THETAs corresponding to priors, if any). Input.
THETA New values of THETA. Output.
THETAP New values of THETA's for priors. Output.

Other reserved variables that may be used are as follows:

NTHETA Number of THETAs to be estimated.
NTHP Number of theta priors.
NPROB IPROB These can be tested in IF statements so that values may be assigned diffently for different problems.

Note that the assignment occurs after the NONMEM control stream has been processed, so that errors in assignment of THETA's are not found. E.g.

1
2


 $THI
 THETA=0.

This will set all theta's to 0, and there will be no specific error message from NONMEM, though most likely the run will fail.

If initial estimates of all or part of THETA are omitted, NONMEM performs a search for missing initial estimates as its first task. (These are printed on a separate page under the heading "INITIAL PARAMETER ESTIMATE"). This search occurs before the transformation by $THETAI.

Values of INITIAL ESTIMATE OF THETA in NONMEM output are those from the $THETA and $THETAP records. Values of THETA in the root.ext files are as set in $THI.

Another example is rescaling THETAs. E.g., suppose in CONTROL5

1

$THETA  (.1,3,5) (.008,.08,.5) (.004,.04,.9)

is replaced with

1
2
3


$THETAI
THETA=THETAI/10.
$THETA  (1,30,50) (.08,.8,5) (.04,.4,9)

The results will be identical, except for the values of INITIAL ESTIMATE OF THETA in the NONMEM report. The values in .ext will not be affected. One can use

1
2


  $THETAR
  THETAR=THETA*10.

to report in the original domain.

$THETAR

Using $THETAR affects the following data in the output report:

1
2
3
4
5
6


 NPARAMETR
 FINAL PARAMETER ESTIMATE for THETA.
 FIRST ORDER STANDARD ERROR OF ESTIMATE
  THETA - VECTOR OF FIXED EFFECTS PARAMETERS
 FIRST ORDER COVARIANCE MATRIX OF ESTIMATE
  THETA - VECTOR OF FIXED EFFECTS PARAMETERS

Contents of additional output files such as .coi and .cov and .cor are also affected.

The assignment statements may be any Fortran 95 statements. They are copied unchanged to subroutine SUBROUTINE THETARSUB in FSUBS (also found in thetair.f90).

They may include array assigment statements specifying the whole arrays or sections of arrays.

Arguments of the subroutine are as follows.

THETA Final estimates of theta. Input.
THETAP Final estimates of THETAs specified on $THETAP records (or, if the informative names are not used, THETAs corresponding to priors, if any). Input.
THETAR New values of THETA. Output
THETAPR New values of THETA's for priors. Output.

Other reserved variables that may be used are as follows:

NTHETA Number of THETAs to be estimated.
NTHP Number of theta priors.
NPROB IPROB These can be tested in IF statements so that values may be assigned diffently for different problems.

If the range is not specified, NONMEM to supply the range (which is by default NTHETA+NTHP).