xpose4 (version 4.5.0)

compute.cwres: Compute the Conditional Weighted Residuals

Description

This function computes the conditional weighted residuals (CWRES) from a NONMEM run. CWRES are an extension of the weighted residuals (WRES), but are calculated based on the first-order with conditional estimation (FOCE) method of linearizing a pharmacometric model (WRES are calculated based on the first-order (FO) method). The function requires a NONMEM table file and an extra output file that must be explicitly asked for when running NONMEM, see details below.

Usage

compute.cwres(run.number,
              tab.prefix="cwtab",
              sim.suffix="",
              est.tab.suffix=".est",
              deriv.tab.suffix=".deriv",
              old.file.convention=FALSE,
              id="ALL",
              printToOutfile=TRUE,
              onlyNonZero=TRUE,
              ...)
xpose.calculate.cwres(object,
                      cwres.table.prefix = "cwtab",
                      tab.suffix = "",
                      sim.suffix = "sim",
                      est.tab.suffix=".est",
                      deriv.tab.suffix=".deriv",
                      old.file.convention=FALSE,
                      id = "ALL",
                      printToOutfile = TRUE,
                      onlyNonZero = FALSE,
                      classic = FALSE,
                      ...)

Arguments

run.number

The run number of the NONMEM from which the CWRES are to be calculated.

tab.prefix

The prefix to two NONMEM file containing the needed values for the computation of the CWRES, described in the details section.

sim.suffix

The suffix ,before the ".", of the NONMEM file containing the needed values for the computation of the CWRES, described in the details section. For example, the table files might be named cwtab1sim.est and cwtab1sim.deriv

est.tab.suffix

The suffix, after the ".", of the NONMEM file containing the estimated parameter values needed for the CWRES calculation.

deriv.tab.suffix

The suffix, after the ".", of the NONMEM file containing the derivatives of the model with respect to the random parameters needed for the CWRES calculation.

old.file.convention

For backwards compatibility. Use this if you are using the previous file convention for CWRES (table files named cwtab1, cwtab1.50, cwtab1.51, ... , cwtab.58 for example).

id

Can be either "ALL" or a number matching an ID label in the datasetname. Value is fixed to "ALL" for xpose.calculate.cwres.

printToOutfile

Logical (TRUE/FALSE) indicating whether the CWRES values calculated should be appended to a copy of the datasetname. Only works if id="ALL". If chosen the resulting output file will be datasetname.cwres

onlyNonZero

Logical (TRUE/FALSE) indicating if the return value (the CWRES values) of compute.cwres should include the zero values associated with non-measurement lines in a NONMEM data file.

object

An xpose.data object.

cwres.table.prefix

The prefix to the NONMEM table file containing the derivative of the model with respect to the etas and epsilons, described in the details section.

tab.suffix

The suffix to the NONMEM table file containing the derivative of the model with respect to the etas and epsilons, described in the details section.

classic

Indicates if the function is to be used in the classic menu system.

...

Other arguments passed to basic functions in code.

Value

• compute.cwres
  Returns a vector containing the values of the CWRES.
• xpose.calculate.cwres
  Returns an Xpose data object that contains the CWRES. If simulated data is present, then the CWRES will also be calculated for that data.

Setting up the NONMEM model file

In order for this function to calculate the CWRES, NONMEM must be run while requesting certain tables and files to be created. How these files are created differs depending on if you are using $PRED or ADVAN as well as the version of NONMEM you are using. These procedures are known to work for NONMEM VI but may be different for NONMEM V. We have attempted to indicate where NONMEM V may be different, but this has not been extensively tested!

This procedure can be done automatically using Perl Speaks NONMEM (PsN) and we highly recommend using PsN for this purpose. After installing PsN just type 'execute [modelname] -compute_cwres'. See http://psn.sourceforge.net for more details. There are five main insertions needed in your NONMEM control file:

1. \$ABB COMRES=X.

{

Insert this line directly after your $DATA line. The value of X is the number of ETA() terms plus the number of EPS() terms in your model. For example for a model with three ETA() terms and two EPS() terms the code would look like this: $DATA temp.csv IGNORE=@ $ABB COMRES=5 $INPUT ID TIME DV MDV AMT EVID $SUB ADVAN2 TRANS2 } Verbatim code.{

• Using ADVAN.

{ If you are using ADVAN routines in your model, then Verbatim code should be inserted directly after the $ERROR section of your model file. The length of the code depends again on the number of ETA() terms and EPS() terms in your model. For each ETA(y) in your model there is a corresponding term G(y,1) that you must assign to a COM() variable. For each EPS(y) in your model, there is a corresponding HH(y,1) term that you must assign to a COM() variable. For example for a model using ADVAN routines with three ETA() terms and two EPS() terms the code would look like this: "LAST " COM(1)=G(1,1) " COM(2)=G(2,1) " COM(3)=G(3,1) " COM(4)=HH(1,1) " COM(5)=HH(2,1) } Using PRED.{

If you are using $PRED, the verbatim code should be inserted directly after the $PRED section of your model file. For each ETA(y) in your model there is a corresponding term G(y,1) that you must assign to a COM() variable. For each EPS(y) in your model, there is a corresponding H(y,1) term that you must assign to a COM() variable. The code would look like this for three ETA() terms and two EPS() terms: "LAST " COM(1)=G(1,1) " COM(2)=G(2,1) " COM(3)=G(3,1) " COM(4)=H(1,1) " COM(5)=H(2,1) } }

item

• INFN routine.
• Using ADVAN with NONMEM V.
• Using $PRED with NONMEM VI.
• Using $PRED with NONMEM V.
• cwtab*.deriv table file.
• $ESTIMATION.

itemize

• Using ADVAN with NONMEM VI.

preformatted

$TABLE ID COM(1)=G11 COM(2)=G21 COM(3)=G31 COM(4)=H11 COM(5)=H21 IPRED MDV NOPRINT ONEHEADER FILE=cwtab1.deriv

code

POSTHOC

Details

[object Object],[object Object]

References

Hooker A, Staatz CE, Karlsson MO. Conditional weighted residuals, an improved model diagnostic for the FO/FOCE methods. PAGE 15 (2006) Abstr 1001 [http://www.page-meeting.org/?abstract=1001].

Examples

## Capture CWRES from cwtab5.est and cwtab5.deriv
cwres <- compute.cwres(5)
mean(cwres)
var(cwres)

## Capture CWRES from cwtab1.est and cwtab1.deriv, do not print out, allow zeroes
cwres <- compute.cwres("1", printToOutFile = FALSE,
  onlyNonZero = FALSE)

## Capture CWRES for ID==1
cwres.1 <- compute.cwres("1", id=1)

## xpdb5 is an Xpose data object
## We expect to find the required NONMEM run and table files for run
## 5 in the current working directory
xpdb5 <- xpose.data(5)

## Compare WRES, CWRES
xpdb5 <- xpose.calculate.cwres(xpdb5)
cwres.wres.vs.idv(xpdb5)