Prerequisites

The following need to be installed and available:

  • PsN >= 4.4.8
  • NONMEM installed with valid license
  • RStudio

First time set up

Set up code completion

It is highly recommended to set up code completion though as it eases the scripting process.

This will ask for user consent as it will add entries to the user level snippets file.

Verify installation

The following function checks for availability of PsN via system_nm(), this is a requirement for NMproject. There are also subsequent checks which not mandatory, but recommended for full functionality.

#> Test passed 🌈

Users working on a standalone machines (e.g. laptops and desktops) should expect these tests to pass and for NMproject to work out of the box (provided the pre-requisites are met).

Custom configuration

More complex environments involving multiple servers and grids may require more configuration. The options shown here aim to facilitate that. You may need the help of an admin.

NMTRAN checks

If working in a grid environment, it is highly recommended to perform NMTRAN checks prior to sending jobs off the grid. NMTRAN check provides immediate feedback of control file and dataset errors allowing you to address problems quickly just like if you were on a laptop/desktop environment. Without this, having to wait for a job to reach the grid and fail is a much slower (and more annoying) process.

NMproject tries to guess the location to the NMTRAN file in the NONMEM installation directory however if this fails and check_installation() cannot detect it, you will need to specify the NMTRAN command/file with the nm_tran_command() function. See the following for instructions and examples at the bottom of the help file:

nm_tran_command("/opt/NONMEM/nm75/tr/NMTRAN.exe")

To see more examples see ?nm_tran_command.

This setting will reset upon R session restart, if you want to make it permanent see Making configuration changes permanent.

The system_nm() command

Under the hood, all calls to PsN proceed through the system_nm() command. This is a user configurable function. By default it’s the same as system() on unix systems and shell() on windows. However if the NONMEM server is remote and requires connection (e.g. via SSH), users may want to modify the behaviour of system_nm(). This is possible through setting the option() also named system_nm, e.g. the following allows runs the system() command on a remote machine named clustername:

options(system_nm=function(cmd,...) {
        system(paste0("ssh -q clustername \"cd $(pwd); ", cmd, "\""),...)
})

This setting will reset upon R session restart, if you want to make it permanent see Making configuration changes permanent.

Custom code library location

NMproject ships with a code library that can be used without configuration. If however you want to have a custom code library, the option code_library_path can be used to set this. For example:

options(code_library_path = "/projects/myorganisation/code_library")

To see more information see ?code_library.

This setting will reset upon R session restart, if you want to make it permanent see Making configuration changes permanent.

Custom directory structures

If your organisation prefers a project directory sub-structure which is different from the standard this can be configured with the function nm_default_dirs(). For example if your organisation performs NONMEM modelling in a directory called “NONMEM” and has a set structure for other sub-directories, you may have something like:

nm_default_dirs(list(
  models = "NONMEM",
  scripts = "RSCRIPTS",
  results = "OUTPUTS",
  source_data = "DATA/SOURCE",
  derived_data = "DATA/DERIVED"
))

To see more examples see ?nm_default_dirs.

This setting will reset upon R session restart, if you want to make it permanent see Making configuration changes permanent.

Custom object properties

If you have a custom PsN command you tend to submit for all NONMEM jobs, use the nm_default_fields function. For example to set a default parafile and modify the basic "execute {ctl_name} -dir={run_dir}" command to use this parafile, you would use the command:

nm_default_fields(list(
  parafile = "/opt/NONMEM/nm75/run/mpilinux8.pnm"
  cmd = "execute -parafile={parafile} {ctl_name} -dir={run_dir} -nodes={cores}"
))

To see more examples see ?nm_default_fields.

This setting will reset upon R session restart, if you want to make it permanent see Making configuration changes permanent.

Making configuration changes permanent

Via startup scripts

Whether it be a custom NMTRAN path, system_nm option or a different default directory structure, to make the above changes permanent, they need to be executed every R session.

R has a few mechanisms for achieving this. See ?.Rprofile for details. The following will open your config file:

usethis::edit_r_profile()

Then insert the configuration code into this file and restart R. For example a custom NMTRAN path can be set permanently to "/opt/NONMEM/nm75/tr/NMTRAN.exe" by including nm_tran_command("/opt/NONMEM/nm75/tr/NMTRAN.exe") into the file.

To set the option site wide you can use the file $R_HOME/etc/Rprofile.site (requires administration privileges).

Via a custom package

If you already have a package you maintain to deliver functions to users, this package can be used to configure set up options via the .onLoad hook. For example, the following will configure custom NMTRAN and code library settings on package load

.onLoad <- function(libname, pkgname){
  ## custom NMTRAN location  
  NMproject::nm_tran_command("/opt/NONMEM/nm75/tr/NMTRAN.exe")
  ## custom code library location
  options(code_library_path = "/projects/myorganisation/code_library")
  ## message to users in interactive sessions
  if (interactive()) usethis::ui_done("NMproject configured")
  
}

The advantage of a package is you can also bundle other functions in there for users to use.