Find and read input data and optionally translate column names according to the $INPUT section

This function finds and reads the input data based on a control stream file path. It can align the column names to the definitions in $INPUT in the control stream, and it can subset the data based on ACCEPT/IGNORE statements in $DATA. It supports a few other ways to identify the input data file than reading the control stream, and it can also read an rds or fst file instead of the delimited text file used by Nonmem.

NMscanInput(
  file,
  formats.read,
  file.mod,
  dir.data = NULL,
  file.data = NULL,
  apply.filters = FALSE,
  translate = TRUE,
  recover.cols = TRUE,
  details = TRUE,
  col.id = "ID",
  col.row,
  quiet,
  args.fread,
  invert = FALSE,
  as.fun,
  applyFilters,
  use.rds
)

Arguments

file

a .lst (output) or a .mod (input) control stream file. The filename does not need to end in .lst. It is recommended to use the output control stream because it reflects the model as it was run rather than how it is planned for next run. However, see file.mod and dir.data.

formats.read

Prioritized input data file formats to look for and use if found. Default is c("rds","csv") which means rds will be used if found, and csv if not. fst is possible too. Default can be modified using NMdataConf().

file.mod

The input control stream file path. Default is to look for \"file\" with extension changed to .mod (PSN style). You can also supply the path to the file, or you can provide a function that translates the output file path to the input file path. If dir.data is missing, the input control stream is needed. This is because the .lst does not contain the path to the data file. The .mod file is only used for finding the data file. How to interpret the datafile is read from the .lst file. The default can be configured using NMdataConf. See dir.data too.

dir.data

The data directory can only be read from the control stream (.mod) and not from the output file (.lst). So if you only have the output file, use dir.data to tell in which directory to find the data file. If dir.data is provided, the .mod file is not used at all.

file.data

Specification of the data file path. When this is used, the control streams are not used at all.

apply.filters

If TRUE (default), IGNORE and ACCEPT statements in the Nonmem control streams are applied before returning the data.

translate

If TRUE (default), data columns are named as interpreted by Nonmem (in $INPUT). If data file contains more columns than mentioned in $INPUT, these will be named as in data file (if data file contains named variables).

recover.cols

recover columns that were not used in the Nonmem control stream? Default is TRUE. Can only be negative when translate=FALSE.

details

If TRUE, metadata is added to output. In this case, you get a list. Typically, this is mostly useful if programming up functions which behavior must depend on properties of the output. See details.

col.id

The name of the subject ID column. Optional and only used to calculate number of subjects in data. Default is modified by NMdataConf.

col.row

The name of the row counter column. Optional and only used to check whether the row counter is in the data.

quiet

Default is to inform a little, but TRUE is useful for non-interactive stuff.

args.fread

List of arguments passed to fread. Notice that except for "input" and "file", you need to supply all arguments to fread if you use this argument. Default values can be configured using NMdataConf.

invert

If TRUE, the data rows that are dismissed by the Nonmem data filters (ACCEPT and IGNORE) and only this will be returned. Only used if apply.filters is TRUE.

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.tables are wanted, use as.fun="data.table". The default can be configured using NMdataConf.

applyFilters

Deprecated - use apply.filters.

use.rds

Deprecated - use formats.read instead. If provided (though not recommended), this will overwrite formats.read, and only formats rds and csv can be used.

Value

A data set, class defined by 'as.fun'

Details

Columns that are dropped (using DROP or SKIP in $INPUT) in the model will be included in the output.

It may not work if a column is dropped, and a new column is renamed to the same name. Say you have DV and CONC as the only two columns (not possible but illustrative), and in Nonmem you do DV=DROP DV. Not sure it will work in Nonmem, and it probably won't work in NMscanInput.

See also

Other DataRead: NMreadCsv(), NMreadTab(), NMscanData(), NMscanTables()