Create a new (parent) nm object

Create a new parent nm object. Normally the first NONMEM object you create will be using this function. Subsequent objects created with the child() function will inherit the properties of the parent run.

new_nm(based_on, run_id = NA_character_, data_path, cmd, force = FALSE)

Arguments

based_on

Character. Relative path to an existing control file from which to base this run. NMproject will not modify or run this control file. Instead it will create a new control file specified by the ctl_name field (see Details below).

run_id

Character. Run identifier. This is used to name the run and output files such as $TABLE outputs.

data_path

Character. Path to dataset. If this is not specified, NMproject will try to guess based on the current $DATA components of the file specified in based_on. However it is recommended to specify this explicitly as a relative path.

cmd

Optional character. PsN command to use. If unspecified will use getOption("nm_default_fields") value of cmd. Use glue notation for inheritance. See details.

force

(Default = FALSE). Forces object creation even if based_on model is in the nm_dir("models") directory.

Value

An object of class nm_list. Attributes can be viewed by printing the object in the console.

Details

The cmd field uses glue notation. So instead of specifying execute runm1.mod -dir=m1, it is best to specify execute {ctl_name} -dir={run_dir}. The values of ctl_name and run_dir refer to object fields and if these change value like when the child() function is used to create a separate child object, the cmd field will update automatically.

Object fields

Each field has a corresponding function (documented in nm_getsetters) of the same name to access and modify it's value.

type

The PsN run type. Default is execute.

run_id

The run identifier. E.g. m1.

run_in

The directory to copy control files and run NONMEM. Default = "Models".

executed

For internal use.

ctl_contents

Stores the contents of the control file to be written to disk when the run_nm() function is used on the object.

data_path

Path to the NONMEM ready dataset (from base project directory).

cmd

See details above.

cores

Numbers of cores to use. Requires a cmd value that uses the {cores} glue field.

run_dir

PsN directory to run the NONMEM run. Default is to the be the same as the run_id for simplicity.

results_dir

Location to store results files from diagnostic reports executed with nm_render().

unique_id

For internal use.

lst_path

Normally does not require setting. Path to the expected .lst file.

See also

nm_getsetters(), child()

Examples

# create example object m1 from package demo files
exdir <- system.file("extdata", "examples", "theopp", package = "NMproject")
m1 <- new_nm(run_id = "m1", 
             based_on = file.path(exdir, "Models", "ADVAN2.mod"),
             data_path = file.path(exdir, "SourceData", "THEOPP.csv"))

m1 ## display object fields
#> List of 1
#>  $ execute.Models/m1
#>   ..$ type        : chr "execute"
#>   ..$ run_id      : chr "m1"
#>   ..$ run_in      : chr "Models"
#>   ..$ executed    : logi FALSE
#>   ..$ ctl_contents: chr collapsed - view with ctl_contents()
#>   ..$ ctl_orig    : chr collapsed - view with ctl_orig()
#>   ..$ data_path   : chr "/Users/runner/work/_temp/Library/NMproject/extdata/examples/theopp/SourceData/THEOPP.csv"
#>   ..$ cmd         : chr "execute runm1.mod -dir=m1"
#>   ..$ cores       : int 1
#>   ..$ parafile    : chr "path/to/parafile.pnm"
#>   ..$ run_dir     : chr "m1"
#>   ..$ ctl_name    : chr "runm1.mod"
#>   ..$ results_dir : chr "Results"
#>   ..$ unique_id   : chr "execute.Models/m1"
#>   ..$ lst_path    : chr "m1/NM_run1/psn.lst"
#>   ..- attr(*, "class")= chr [1:3] "nm_execute" "nm_generic" "list"
#>  - attr(*, "class")= chr [1:2] "nm_list" "list"
cmd(m1)
#> [1] "execute runm1.mod -dir=m1"
ctl_name(m1)
#> [1] "runm1.mod"
run_dir(m1)
#> [1] "m1"