Read information from Nonmem ext files

Source: R/NMreadExt.R

Read information from Nonmem ext files

NMreadExt(
  file,
  return,
  as.fun,
  modelname,
  col.model,
  auto.ext,
  tableno = "max",
  file.ext
)

Arguments

file

Path to the ext file

return

The .ext file contains both final parameter estimates and iterations of the estimates. If return="pars" (default) the final estimates are returned in addition to what other parameter-level information is found, like FIX, sd etc. as columns. If return="iterations", the iterations are returned (including objective function value). If return="obj" objective function value at final estimate is returned. If return="all", all er returned, though in separate data.frames compiled in a list.

as.fun

The default is to return data as a data.frame. Pass a function (say `tibble::as_tibble`) in as.fun to convert to something else. If `data.table`s are wanted, use `as.fun="data.table"`. The default can be configured using `NMdataConf()`.

modelname

See `?NMscanData`

col.model

See `?NMscanData`

auto.ext

If `TRUE` (default) the extension will automatically be modified using `NMdataConf()$file.ext`. This means `file` can be the path to an input or output control stream, and `NMreadExt` will still read the `.ext` file.

tableno

In case the ext file contains multiple tables, this argument controls which one to choose. The options are

  • "max" (default) Pick the table with the highest table number. This typically means the results from the last `$ESTIMATION` step are used.

  • "min" Pick results from the first table available.

  • "all" Keep all results. The tables can be distinguished by the `tableno` column.

  • an integer greater than 0, in which case the table with this table number will be picked.

file.ext

Deprecated. Please use file instead.

Value

If return="all", a list with a final parameter table and a table of the iterations. If return="pars", only the parameter table, and if return="iterations" only the iterations table. If you need both, it may be more efficient to only read the file once and use return="all". Often, only one of the two are needed, and it more convenient to just extract one.

Details

The parameter table returned if return="pars" or return="all" will contain columns based on the Nonmem 7.5 manual. It defines codes for different parameter-level values. They are:

-1e+09: se -1000000002: eigCor -1000000003: cond -1000000004: stdDevCor -1000000005: seStdDevCor -1000000006: FIX -1000000007: termStat -1000000008: partLik

The parameter name is in the parameter column. The "parameter type", like "THETA", "OMEGA", "SIGMA" are available in the par.type column. Counters are available in i and j columns. j will be NA for par.type=="THETA"

The objective function value is included as a parameter.

Notice that in case multiple tables are available in the `ext` file, the column names are taken from the first table. E.g., in case of SAEM/IMP estimation, the objective function values will be in the `SAEMOBJ` column, even for the IMP step. This may change in the future.