Configure default behavior of NMdata functions

Source: R/NMdataConf.R

Configure default behavior across the functions in NMdata rather than typing the arguments in all function calls. Configure for your file organization, data set column names, and other NMdata behavior. Also, you can control what data class NMdata functions return (say data.tables or tibbles if you prefer one of those over data.frames).

NMdataConf(..., allow.unknown = FALSE)

Arguments

...

NMdata options to modify. These are named arguments, like for base::options. Normally, multiple arguments can be used. The exception is if reset=TRUE is used which means all options are restored to default values. If NULL is passed to an argument, the argument is reset to default. is See examples for how to use.

allow.unknown

Allow to store configuration of variables that are not pre-defined in NMdata. This should only be needed in cases where say another package wants to use the NMdata configuration system for variables unknown to NMdata.

Parameters that can be controlled are:

  • args.fread Arguments passed to fread when reading _input_ data files (fread options for reading Nonmem output tables cannot be configured at this point). If you change this, you are starting from scratch, except from file. This means that existing default argument values are all disregarded.

  • args.fwrite Arguments passed to fwrite when writing csv files (NMwriteData). If you use this, you have to supply all arguments you want to use with fwrite, except for x (the data) and file.

  • as.fun A function that will be applied to data returned by various data reading functions (NMscanData, NMreadTab, NMreadCsv, NMscanInput, NMscanTables). Also, data processing functions like mergeCheck, findCovs, findVars, flagsAssign, flagsCount take this into account, but slightly differently. For these functions that take data as arguments, the as.fun configuration is only taken into account if a the data passed to the functions are not of class data.table. The argument as.fun to these functions is always adhered to. Pass an actual function, say as.fun=tibble::as_tibble. If you want data.table, use as.fun="data.table" (not a function).

  • check.time Logical, applies to NMscanData only. NMscanData by defaults checks if output control stream is newer than input control stream and input data. Set this to FALSE if you are in an environment where time stamps cannot be relied on.

  • col.flagc The name of the column containing the character flag values for data row omission. Default value is flag. Used by flagsAssign, flagsCount.

  • col.flagn The name of the column containing numerical flag values for data row omission. Default value is FLAG. Used by flagsAssign, flagsCount, NMcheckData.

  • col.model The name of the column that will hold the name of the model. See modelname too (which defines the values that the column will hold).

  • col.nmout A column of this name will be a logical representing whether row was in output table or not.

  • col.nomtime The name of the column holding nominal time. This is only used for sorting columns by NMorderColumns.

  • col.row The name of the column containing a unique row identifier. This is used by NMscanData when merge.by.row=TRUE, and by NMorderColumns (row counter will be first column in data).

  • col.id The name of the column holding the numeric subject ID. As of `NMdata` 0.1.5 this is only used for sorting columns by NMorderColumns.

  • col.time The name of the column holding actual time. As of `NMdata` 0.1.5 this is only used for sorting columns by NMorderColumns.

  • dir.psn The directory in which to find psn executables like `execute` and `update_inits`. Default is "" meaning that executables must be in the system search path. Not used by NMdata.

  • dir.res Directory in which `NMsim` will store simulation results files. Not used by NMdata. See dir.sims too.

  • dir.sims Directory in which `NMsim` will store Nonmem simulations. Not used by NMdata. See dir.res too.

  • file.cov A function that will derive the path to the covariance (.cov) output file stream based on the path to the output control stream. Technically, it can be a string too, but when using NMdataConf, this would make little sense because it would direct all output control streams to the same input control streams.

  • file.ext A function that will derive the path to the parameter (.ext) output file stream based on the path to the output control stream. Technically, it can be a string too, but when using NMdataConf, this would make little sense because it would direct all output control streams to the same input control streams.

  • file.mod A function that will derive the path to the input control stream based on the path to the output control stream. Technically, it can be a string too, but when using NMdataConf, this would make little sense because it would direct all output control streams to the same input control streams.

  • file.phi A function that will derive the path to the Nonmem output (.phi) file containing individual ETA, ETC, and/or PHI values stream based on the path to the output control stream. Technically, it can be a string too, but when using NMdataConf, this would make little sense because it would direct all output control streams to the same input control streams.

  • file.data A function that will derive the path to the input data based on the path to the output control stream. Technically, it can be a string too, but when using NMdataConf, this would make little sense because it would direct all output control streams to the same input control streams.

  • 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.

  • formats.write character vector of formats.write. Default is c("csv","rds"). "fst" is possible too.

  • merge.by.row Adjust the default combine method in NMscanData.

  • modelname A function that will translate the output control stream path to a model name. Default is to strip .lst, so /path/to/run1.lst will become run1. Technically, it can be a string too, but when using NMdataConf, this would make little sense because it would translate all output control streams model name.

  • path.nonmem Path (a character string) to a nonmem executable. Not used by NMdata. Default is NULL.

  • quiet For non-interactive scripts, you can switch off the chatty behavior once and for all using this setting.

  • recover.rows In NMscanData, Include rows from input data files that do not exist in output tables? This will be added to the $row dataset only, and $run, $id, and $occ datasets are created before this is taken into account. A column called nmout will be TRUE when the row was found in output tables, and FALSE when not. Default is FALSE.

  • use.input In NMscanData, merge with columns in input data? Using this, you don't have to worry about remembering including all relevant variables in the output tables. Default is TRUE.

  • use.rds Deprecated, use formats.read and formats.write instead. Affects NMscanData(), NMscanInput(), NMwriteData().

Value

If no arguments given, a list of active settings. If arguments given and no issues found, TRUE invisibly.

Details

Recommendation: Use this function transparently in the code and not in a configuration file hidden from other users.

Examples

## get current defaults
NMdataConf()
#> $args.fread
#> $args.fread$na.strings
#> [1] "."
#> 
#> $args.fread$header
#> [1] TRUE
#> 
#> 
#> $args.fwrite
#> $args.fwrite$na
#> [1] "."
#> 
#> $args.fwrite$quote
#> [1] FALSE
#> 
#> $args.fwrite$row.names
#> [1] FALSE
#> 
#> $args.fwrite$scipen
#> [1] 0
#> 
#> 
#> $as.fun
#> function (x, row.names = NULL, optional = FALSE, ...) 
#> {
#>     if (is.null(x)) 
#>         return(as.data.frame(list()))
#>     UseMethod("as.data.frame")
#> }
#> <bytecode: 0x565388dc8050>
#> <environment: namespace:base>
#> 
#> $check.time
#> [1] TRUE
#> 
#> $col.flagc
#> [1] "flag"
#> 
#> $col.flagn
#> [1] "FLAG"
#> 
#> $col.id
#> [1] "ID"
#> 
#> $col.model
#> [1] "model"
#> 
#> $col.nmout
#> [1] "nmout"
#> 
#> $col.nomtime
#> [1] "NOMTIME"
#> 
#> $col.row
#> [1] "ROW"
#> 
#> $col.time
#> [1] "TIME"
#> 
#> $dir.psn
#> [1] ""
#> 
#> $file.ext
#> function (file) 
#> {
#>     fnExtension(file, ext = ".ext")
#> }
#> <bytecode: 0x565388dab5c0>
#> <environment: 0x565388dc8980>
#> 
#> $file.cov
#> function (file) 
#> {
#>     fnExtension(file, ext = ".cov")
#> }
#> <bytecode: 0x565388dabc88>
#> <environment: 0x565388dc8980>
#> 
#> $file.phi
#> function (file) 
#> {
#>     fnExtension(file, ext = ".phi")
#> }
#> <bytecode: 0x565388da6600>
#> <environment: 0x565388dc8980>
#> 
#> $file.shk
#> function (file) 
#> {
#>     fnExtension(file, ext = ".shk")
#> }
#> <bytecode: 0x565388da6cc8>
#> <environment: 0x565388dc8980>
#> 
#> $file.mod
#> function (file) 
#> {
#>     mod <- fnExtension(file, ext = ".mod")
#>     ctl <- fnExtension(file, ext = ".ctl")
#>     if (file.exists(mod)) {
#>         if (file.exists(ctl)) 
#>             stop("both .mod and .ctl found. Please define file.mod to choose one of them")
#>         return(mod)
#>     }
#>     ctl
#> }
#> <bytecode: 0x565388da7390>
#> <environment: 0x565388dc8980>
#> 
#> $file.data
#> [1] "extract"
#> 
#> $merge.by.row
#> [1] "ifAvailable"
#> 
#> $modelname
#> function (file) 
#> fnExtension(basename(file), "")
#> <bytecode: 0x565388da8200>
#> <environment: 0x565388dc8980>
#> 
#> $nc
#> [1] 64
#> 
#> $quiet
#> [1] FALSE
#> 
#> $recover.rows
#> [1] FALSE
#> 
#> $use.input
#> [1] TRUE
#> 
#> $formats.read
#> [1] "rds" "csv"
#> 
#> $formats.write
#> [1] "rds" "csv"
#> 
## change a parameter
NMdataConf(check.time=FALSE)
## reset one parameter to default value
NMdataConf(modelname=NULL)
## reset all parameters to defaults
NMdataConf(reset=TRUE)