Import NONMEM output into R — xpose

Gather model outputs into a R database

xpose_data(
  runno = NULL,
  prefix = "run",
  ext = ".lst",
  file = NULL,
  dir = NULL,
  gg_theme = theme_readable,
  xp_theme = theme_xp_default(),
  simtab = NULL,
  manual_import = NULL,
  ignore = NULL,
  check_ext = TRUE,
  extra_files,
  quiet,
  ...
)

Arguments

runno: Run number to be used to generate model file name. Used in combination with prefix and ext.
prefix: Prefix to be used to generate model file name. Used in combination with runno and ext.
ext: Extension to be used to generate model file name. Should be one of '.lst' (default), '.out', '.res', '.mod' or '.ctl' for NONMEM.
file: Model file name (preferably a '.lst' file) containing the file extension. Alternative to prefix, runno and ext arguments.
dir: Location of the model files.
gg_theme: A complete ggplot2 theme object (e.g. theme_classic), or a function returning a complete ggplot2 theme.
xp_theme: A complete xpose theme object (e.g. theme_xp_default).
simtab: If TRUE only reads in simulation tables, if FALSE only reads estimation tables. Default NULL reads all tables. Option not compatible with manual_import.
manual_import: If NULL (default) the names of the output tables to import will be obtained from the model file. To manually import files as in previous versions of xpose, the check the function manual_nm_import.
ignore: Character vector be used to ignore the import/generation of: 'data', 'files', 'summary' or any combination of the three.
check_ext: Logical, if TRUE will provide an error message if the extension of the NONMEM input file is not one of '.lst', '.out', '.res', '.mod' or '.ctl' for NONMEM. If FALSE any file extension can be used.
extra_files: A vector of additional output file extensions to be imported. Default is '.ext', '.cov', '.cor', '.phi', '.grd' for NONMEM.
quiet: Logical, if FALSE messages are printed to the console.
...: Additional arguments to be passed to the read_nm_tables functions.

File path generation

The rules for model file names generation are as follow:

with runno: the full path is generated as <dir>/<prefix><runno>.<ext> e.g. with dir = 'model/pk', prefix = 'run', runno = '001', ext = '.lst' the resulting path would be model/pk/run001.lst
with file: the full path is generated as <dir>/<file> e.g. with dir = 'model/pk', file = 'run001.lst' the resulting path would also be model/pk/run001.lst. Note: in this case the file extension should be provided as part of the `file` argument.

Table format requirement

When importing data, an ID column must be present in at least one table for each problem and for each `firstonly` category. ID columns are required to properly combine/merge tables and removing NA records. If ID columns are missing xpose will return the following warning: Dropped `<tablenames>` due to missing required `ID` column.

Examples

if (FALSE) {
# Using the `file` argument to point to the model file:
xpdb <- xpose_data(file = 'run001.lst', dir = 'models')

# Using the `runno` argument to point to the model file:
xpdb <- xpose_data(runno = '001', ext = '.lst', dir = 'models')

# Using the `extra_files` argument to import specific output files only:
xpdb <- xpose_data(file = 'run001.lst', dir = 'models', extra_files = c('.ext', '.phi'))

# Using `ignore` to disable import of tables and output files:
xpdb <- xpose_data(file = 'run001.lst', dir = 'models', ignore = c('data', 'files'))

# Using `simtab` to disable import of simulation tables
xpdb <- xpose_data(file = 'run001.lst', dir = 'models', simtab = FALSE)

}