R: Find and read input data and optionally translate column...

NMscanInput {NMdata}

R Documentation

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

Description

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.

Usage

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.

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.

Value